Errors and Solutions

This section outlines basic exceptions that can be generated by Apache Ignite and provides basic instructions for handling them.

Finding Stack Trace Information

When the exception happens, Apache Ignite provides a UUID of the specific exception, but not a full stack trace. For a full stack trace, check cluster logs.

Common Exceptions

Exception Code	Description	Recommended Action
IGN-CMN-1	Operation was stopped because node is stopping.	Check that the cluster is up and running and try again.
IGN-CMN-2	Operation was stopped because the component is not started.	Wait for the node to complete the startup process and start all components.
IGN-CMN-3	Operation failed because an illegal argument or argument in a wrong format has been passed.	Check the exception message for additional information. Specific actions depend on the operation that triggered the error.
IGN-CMN-4	Operation failed because SSL could not be configured.	Check the exception message for more information and update the configuration.
IGN-CMN-5	Operation failed because a node has left the cluster.	Wait for the node to return to the cluster, or use a different node.
IGN-CMN-6	Operation failed because the cursor is already closed.	Check the exception message to find out why the cursor was closed before the operation.
IGN-CMN-7	An error occurred while closing resources.	Check the exception message to find out why the resource was closed before the operation.
IGN-CMN-8	An error occurred while marshalling or unmarshalling objects.
IGN-CMN-9	The method cannot return a null value.
IGN-CMN-65535	Internal error has occurred.	This an unexpected internal error in Apache Ignite. In most cases, receiving it indicates a bug.

Table Exceptions

Exception Code	Description	Recommended Action
IGN-TBL-1	Table already exists.	Make sure to use the table name that does not exist on the cluster.
IGN-TBL-2	Table not found.	Check the table name and, if necessary, create it.
IGN-TBL-3	Column already exists.	Make sure to use the column name that does not exist in the table.
IGN-TBL-4	Column not found.	Check the column name and, if necessary, create it.
IGN-TBL-5	Schema version mismatch.	The request uses a different schema than the table.
IGN-TBL-6	Partition type not supported.	Use a supported partition type.

Client Exceptions

Exception Code	Description	Recommended Action
IGN-CLIENT-1	Connection to client failed. This error is usually caused by incorrect address or connection timeout.	Check the exception message. If a timeout occurred, make sure the timeout values in client and server configurations allow for long-running requests.
IGN-CLIENT-2	An issue occurred with connection protocol. This error can be caused by using an incompatible client version or data corruption.	Check the exception message. If data corruption occurred, recover the data. If client versions are not compatible, use the correct client version.
IGN-CLIENT-3	Protocol version does not support a specific feature. Typically this is caused by version mismatch between client and server.	Update the client or the server to a newer version or do not use incompatible features.
IGN-CLIENT-4	Failed to find the table by ID.	Check if the table ID is correct.
IGN-CLIENT-5	An error occurred with client configuration.	Check the exception message for more information and fix the client configuration.
IGN-CLIENT-6	Cluster ID mismatch. This error can be caused by the client connecting to multiple different clusters.	Check client configuration to make sure all endpoints belong to the same cluster.
IGN-CLIENT-7	Client SSL configuration is not valid.	Check the exception message for more information. Make sure SSL configuration matches server-side configuration.
IGN-CLIENT-8	Client handshake message error. This is usually caused by the client trying to connect to a wrong endpoint (for example, REST) or a non-Apache Ignite process is trying to connect to a Apache Ignite endpoint.	Check the exception message for more information. If the issue is with client, check and fix client configuration. If a third-party client is trying to connect, check what it is and fix the configuration.

SQL Exceptions

Exception Code	Description	Recommended Action
IGN-SQL-1	Exception is thrown when a query doesn't intend to return any rows (for example, a DML or a DDL query).	Change the request to not expect the result from the query.
IGN-SQL-2	Exception is thrown when the specified schema cannot be found.	Make sure you use the existing schema name.
IGN-SQL-3	Statement parsing error. This error is returned when an SQL statement string is not valid according to syntax rules.	Check the exception message and correct issues in the query.
IGN-SQL-4	Statement validation error. Although statement is grammatically correct, the semantic is in question. For example, this can happen when the statement refers to relations that do not exist or describes a prohibited action.	Check the exception message and correct the query.
IGN-SQL-5	Constraint violation error such as primary key violation or NOT NULL.	Check the exception message and correct the query.
IGN-SQL-6	Statement canceled error. Statement is canceled due to timeout, admin action, etc.	Check the exception message to find out the specific reason.
IGN-SQL-7	Runtime error. Errors caused by programming errors in SQL statement itself, such errors happen during statement execution. For example, this can be caused by numeric overflow errors or type conversion errors.	Check the exception message and fix the issue.
IGN-SQL-8	SQL engine was unable to map query on current cluster topology. This may be due to a variety of reasons, but most probably because of all nodes hosting certain system view or a table partition went offline.	Check the exception message. In most scenarios, you can rerun the query when the cluster is stable.
IGN-SQL-9	Execution of transaction control statement inside an external transaction is forbidden.	Do not use transaction control statements like BEGIN TRANSACTION or COMMIT in external transactions, including JDBC with disabled autocommit mode.

Index Exceptions

Exception Code	Description	Recommended Action
IGN-IDX-1	Failed to find the specified index.	Make sure the index exists.
IGN-IDX-2	Specified index already exists.	Make sure the index does not exist when creating it.

Transactions Exceptions

Exception Code	Description	Recommended Action
IGN-TX-1	Default error for transaction state storage.	General error, check the logs and take action depending on the cause. Make sure there are no disk errors.
IGN-TX-2	Storage is stopped.	Storage is stopped due to the node stop or replica stop. No action is required unless this behavior is unexpected. Otherwise check the log for details.
IGN-TX-3	Unexpected transaction state on state change.	This can happen when trying to commit an already aborted transaction or roll back a committed one. No action is required.
IGN-TX-4	Failed to acquire a lock on a key due to a conflict.	The lock is taken by another transaction. Retry the operation or change the deadlock prevention policy.
IGN-TX-5	Failed to acquire a lock on a key within the timeout.	The lock is held by another transaction. Make sure that the other transaction is not hanging, kill it if necessary; or retry the operation.
IGN-TX-6	Failed to commit a transaction.	Take actions depending on the cause. Make sure that all partitions in the cluster have a majority of nodes online in their groups.
IGN-TX-7	Failed to roll back a transaction.	Take actions depending on the cause. Make sure that all partitions in the cluster have a majority of nodes online in their groups.
IGN-TX-8	Failed to put read-write operation into read-only transaction.	The read-write operations within read-only transactions are not possible.
IGN-TX-9	Transaction state storage rebalancing error.	Fix the cause of the rebalancing error, make sure there are no disk errors.
IGN-TX-10	Failed to create a read-only transaction with a timestamp older than the data available in the tables.	Retry the transaction with newer read timestamp. Increase data availability time.
IGN-TX-11	Failure due to an incompatible schema change.	The transaction tried to access data within incompatible schema. Retry the transaction.
IGN-TX-12	Failure due to primary replica expiration.	Retry the transaction. Make sure there are no node failures, network issues or JVM/GC pauses that can cause the primary replica expiration.
IGN-TX-13	Transaction already finished.	This can be caused by any operation within a finished (committed or aborted) transaction. Doesn't require any specific action.
IGN-TX-14	Failure due to a stale operation of a completed transaction.	Error that occurs when a stale operation of a transaction is detected. Try to rerun the transaction, if necessary.
IGN-TX-15	Error occurred when trying to execute an operation in a read-only transaction on a node that has already destroyed data for read timestamp of the transaction.	Retry the transaction with newer read timestamp. Increase data availability time.

Replicator Exceptions

Exception Code	Description	Recommended Action
IGN-REP-1	Default error for the replication procedure.	Check the logs and take action depending on the cause.
IGN-REP-2	Replica with the same identifier already exists.	Replica start error. Check the logs for details.
IGN-REP-3	Replication timeout error.	Potential causes include prolonged replica startup, network issues, or node failures. Check the logs for error cause. Make sure that every partition group has a majority of nodes online.
IGN-REP-4	The replication level tried to handle an unsupported request.	Make sure there are no nodes having incompatible versions in the cluster.
IGN-REP-5	Replica is not ready to handle the request.	This can be caused by the replica unavailability or the primary replica absence. Check the logs for details related to the replica start issues. If the error is caused by the primary replica absence, make sure that partition groups are operational, check the logs for problems related to primary replica negotiation for the specific replication group.
IGN-REP-6	Replica is not the current primary replica.	This error indicates that the request was routed to a node that is not the current primary replica lease holder. Retry the operation, as it should automatically redirect to the correct lease holder. If primary replicas are changing frequently, verify that there are no node failures, network issues, or JVM/GC pauses causing primary replica expiration.
IGN-REP-7	Failed to close cursor.	General error, check the logs for details.
IGN-REP-8	Replica is already stopping.	Replica is being stopped, probably due to the node stop or rebalancing. No action is required unless this behavior is unexpected. Otherwise check the logs for details.

Storage Exceptions

Exception Code	Description	Recommended Action
IGN-STORAGE-1	A disaster has occurred, followed by an attempt to recover from the disaster. This caused inconsistent index state in the cluster metadata.	Wait until the index is rebuilt automatically.
IGN-STORAGE-2	A disaster has occurred, which led to data corruption in the persistent storage.	Restore the data from a backup or introduce a new node instead of the broken one (this may lead to data loss if the replication factor is too low).

Distribution Zone Exceptions

Exception Code	Description	Recommended Action
IGN-DISTRZONES-1	Distribution zone is not found.	Check the distribution zone name used. Most likely, it is incorrect.

Network Exceptions

Exception Code	Description	Recommended Action
IGN-NETWORK-1	The node with the specified ID is not in the physical topology.	Check the error message and node ID. Update node ID if it is incorrect. If the node is offline, check why and bring it back online.
IGN-NETWORK-2	Port is already in use.	Most likely, Apache Ignite tried to access the port occupied by a different process. Change the port or free it, and then restart the node.
IGN-NETWORK-5	Recipient node has left the physical topology.	Check the error message. The node is unavailable and need to be brought back into the cluster.
IGN-NETWORK-6	Could not resolve address. Most likely, the IP address specified in the operation is not available locally.	Change the node configuration to make the address available or use a different IP address.

Node Configuration Exceptions

Exception Code	Description	Recommended Action
IGN-NODECFG-1	Failed to read configuration.	Make sure that the node has access to the configuration file.
IGN-NODECFG-2	Failed to create a configuration file.	Check if the node has write permissions to the folder where configuration is.
IGN-NODECFG-3	Failed to write configuration.	Check if the node has write permissions to the folder where configuration is.
IGN-NODECFG-4	Failed to parse configuration.	Make sure the configuration file is correct.

Code Deployment Exceptions

Exception Code	Description	Recommended Action
IGN-CODEDEPLOY-1	Access attempt to a non-existing deployment unit.	Make sure the deployment unit is specified correctly.
IGN-CODEDEPLOY-2	Duplicate deployment unit.	Make sure deployment unit is unique. Update deployment unit name or version.
IGN-CODEDEPLOY-3	Deployment unit content read error.	Check the error message for details.
IGN-CODEDEPLOY-4	Deployment unit is unavailable for computing.	Check the error message for details.

Authentication Exceptions

Exception Code	Description	Recommended Action
IGN-AUTHENTICATION-1	Authentication error caused by unsupported authentication type.	Check the client configuration and use the supported configuration type.
IGN-AUTHENTICATION-2	Authentication error caused by invalid credentials.	Check and correct user credentials.
IGN-AUTHENTICATION-3	Basic authentication provider is not found.	Configure basic authentication provider.

Compute Exceptions

Exception Code	Description	Recommended Action
IGN-COMPUTE-1	Classpath error.	Check the exception message for additional information and fix the classpath error.
IGN-COMPUTE-2	Class loader error.	Most likely, this is caused by an internal error in Apache Ignite.
IGN-COMPUTE-3	Failed to initialize the job class.	Check the exception message for more information.
IGN-COMPUTE-4	Execution queue overflow.	Increase the compute.queueMaxSize configuration parameter to allow for larger queue.
IGN-COMPUTE-5	Compute job status transition error.	Retry the operation or check job status.
IGN-COMPUTE-6	Failed to cancel compute job.	Check the error message and fix the issue in it.
IGN-COMPUTE-7	Compute job result not found.	Make sure the specified job ID exists.
IGN-COMPUTE-8	Compute job state cannot be retrieved.	Make sure the specified job ID exists. If it does, check the node logs for additional information.
IGN-COMPUTE-9	Compute job failed.	Check the exception message for more information on the reason for failure.
IGN-COMPUTE-10	Failed to resolve primary replica for colocated execution.	Check the exception message for additional information.
IGN-COMPUTE-11	Failed to change job priority.	Check the exception message for additional information.
IGN-COMPUTE-12	Specified node is not found in the cluster.	Make sure the specified node ID is correct and the node with the ID is in the cluster.
IGN-COMPUTE-13	Incompatible types for argument or result in compute job.	Make sure that defined compute job argument and result marshallers match on both server and client sides.
IGN-COMPUTE-14	Compute job cancelled.

Catalog Exceptions

Exception Code	Description	Recommended Action
IGN-CATALOG-1	Command to the catalog has not passed the validation.	See the exception message for details. Typically, this is either caused by incorrect DDL query (same as IGN-SQL-4) or an internal Apache Ignite error.

Critical Workers Exceptions

Exception Code	Description	Recommended Action
IGN-WORKERS-1	System worker does not update its heartbeat for a long time. Typically, this means that the node has stalled or is running slowly.	Restart the node.
IGN-WORKERS-2	System-critical operation timed out.	Restart the node.

Disaster Recovery Exceptions

Exception Code	Description	Recommended Action
IGN-RECOVERY-1	Partition ID is not in valid range.	Check the exception message. Most likely, the specified partition ID is not correct.
IGN-RECOVERY-2	Nodes were not found.	Check the exception message. Most likely, the specified node ID is not correct.
IGN-RECOVERY-3	Failed to recover partition states.	Retry the operation. If it fails again, check the exception message for more information.
IGN-RECOVERY-4	Cluster is under load.	Retry the operation when the cluster has less load.

Metastorage Exceptions

Exception Code	Description	Recommended Action
IGN-META-7	Failed to start a node because metastorage has diverged as a result of MG recovery.	Clear the node of data and add it to the cluster as a blank node.