// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

= Errors and Solutions

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

== Finding Stack Trace Information

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

== Common Exceptions

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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 Ignite. In most cases, receiving it indicates a bug.

|===

== Table Exceptions

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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-Ignite process is trying to connect to a 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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|Exception Code	|Description|Recommended Action

|`IGN-TX-1`|Default error for transaction state storage.|
|`IGN-TX-2`|Transaction state storage is stopped.|
|`IGN-TX-3`|Unexpected transaction state on state change.|
|`IGN-TX-4`|Failed to acquire a lock on a key due to a conflict.|
|`IGN-TX-5`|Failed to acquire a lock on a key within the timeout.|
|`IGN-TX-6`|Failed to commit a transaction.|
|`IGN-TX-7`|Failed to roll back a transaction.|
|`IGN-TX-8`|Failed to put read-write operation into read-only transaction.|
|`IGN-TX-9`|Transaction state storage rebalancing error.|
|`IGN-TX-10`|Failed to create a read-only transaction with a timestamp older than the data available in the tables.|
|`IGN-TX-11`|Failure due to an incompatible schema change.|
|`IGN-TX-12`|Failure due to primary replica expiration.|
|`IGN-TX-13`|Transaction already finished.|
|`IGN-TX-14`|Failure due to a stale operation of a completed transaction.|
|`IGN-TX-15`|Failure due to cache operations enlisted into table transaction or vice versa.|
|===

== Replicator Exceptions

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|Exception Code	|Description|Recommended Action

|`IGN-REP-1`|Default error for the replication procedure.|
|`IGN-REP-2`|Replica with the same identifier already exists.|
|`IGN-REP-3`|Timeout has occurred during the replication procedure.|
|`IGN-REP-4`|The replication level tried to handle an unsupported request.|
|`IGN-REP-5`|Replica is not ready to handle the request.|
|`IGN-REP-6`|Replica is not the current primary replica.|
|`IGN-REP-7`|Failed to close cursor.|
|`IGN-REP-8`|Replica is already stopping.|
|`IGN-REP-9`|Replication safe time reordering.|

|===


== Storage Exceptions

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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, 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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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

[cols="20%,40%,40%", width="100%",opts="header"]
|===
|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 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`|Compute job owner cannot be retrieved.|Check the exception message for additional information and make sure that job owner is correct.
|===

== Catalog Exceptions

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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 Ignite error.
|===

== Critical Workers Exceptions

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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

[cols="20%,40%, 40%", width="100%",opts="header"]
|===
|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.
|===
