docs/_docs/handling-exceptions.adoc

// 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.

= Exceptions

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, Apache 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%,80%", width="100%"]
|===
|Exception	|Description
|`IGN-CMN-1`|Operation was stopped because node is stopping.
|`IGN-CMN-2`|Required component was not started.
|`IGN-CMN-65535`|Internal error.
|===

== Table Exceptions

[cols="20%,80%", width="100%"]
|===
|Exception	|Description
|`IGN-TBL-1`|Table already exists.
|`IGN-TBL-2`|Table not found.
|`IGN-TBL-3`|Column already exists.
|`IGN-TBL-4`|Column not found.
|===

== Client Exceptions

[cols="20%,80%", width="100%"]
|===
|Exception	|Description
|`IGN-CLIENT-1`|Connection to client failed.
|`IGN-CLIENT-2`|An issue happened with connection protocol.
|`IGN-CLIENT-3`|Incompatible protocol version.
|`IGN-CLIENT-4`|Table not found by ID.
|`IGN-CLIENT-5`|An error with authentication parameters.
|`IGN-CLIENT-6`|An error occurred during server authorization.
|`IGN-CLIENT-7`|An error occurred while reading client configuration.
|===

== SQL  Exceptions

[cols="20%,80%", width="100%"]
|===
|Exception	|Description
|`IGN-SQL-1`|Ignite tried to read a page after last one.
|`IGN-SQL-2`|The specified either does not exist or is closed.
|`IGN-SQL-3`|SQL query is incorrect.
|`IGN-SQL-4`|Query returned no result set.
|`IGN-SQL-5`|Table is missing primary key.
|`IGN-SQL-6`|Multiple primary keys found in a table.
|`IGN-SQL-7`|Failed to find schema.
|`IGN-SQL-8`|Specified storage engine is not supported.
|`IGN-SQL-9`|Cursor is already closed when another operation starts.
|`IGN-SQL-10`|Some keys could not be inserted because they are duplicates.
|`IGN-SQL-11`|Cannot delete a column that belongs to the primary key.
|`IGN-SQL-12`|Too many grouping expressions.
|`IGN-SQL-13`|Unsupported SQL operation.
|`IGN-SQL-14`|Unsupported DDL operation.
|`IGN-SQL-15`|Query validation error.
|`IGN-SQL-16`|Specified table not found.
|`IGN-SQL-17`|Specified table version not found.
|`IGN-SQL-18`|Invalid table option specified.
|`IGN-SQL-19`|Query mapping error.
|`IGN-SQL-20`|DDL execution error.
|`IGN-SQL-21`|DML result error.
|`IGN-SQL-22`|Failed to map SQL data type to relational.
|`IGN-SQL-23`|Failed to serialize relational expression.
|`IGN-SQL-24`|Failed to deserialized relational expression.
|`IGN-SQL-25`|Class not found.
|`IGN-SQL-26`|Failed to compile an SQL expression.
|`IGN-SQL-27`|Node left the cluster.
|`IGN-SQL-28`|Failed to send a message.
|`IGN-SQL-29`|Operation aborted or interrupted.
|`IGN-SQL-30`|An error occurred while canceling the operation.
|`IGN-SQL-31`|Session expired.
|`IGN-SQL-32`|Session evaluation error.
|`IGN-SQL-33`|Execution cancelled.
|===

== Meta Storage Exceptions

[cols="20%,80%", width="100%"]
|===
|Exception	|Description
|`IGN-META-1`|Failed to start the underlying key value storage.
|`IGN-META-2`|Failed to restore the underlying key value storage.
|`IGN-META-3`|Failed to close the underlying key value storage.
|`IGN-META-4`|Failed to compact the underlying key value storage.
|`IGN-META-5`|Failed to perform an operation on the underlying key value storage.
|`IGN-META-6`|Failed to perform an operation within a specified time period. Usually in such cases the operation should be retried.
|`IGN-META-7`|Failed to iterate over the underlying key value storage.
|`IGN-META-8`|Failed to stop a watcher.
|`IGN-META-9`|Failed to deploy or update a watcher.
|`IGN-META-10`|Failed to iterate over meta storage cursor.
|`IGN-META-11`|Failed to close a cursor.
|===

== Index Exceptions

[cols="20%,80%", width="100%"]
|===
|Exception	|Description
|`IGN-IDX-1`|Invalid index definition.
|`IGN-IDX-2`|Failed to find the specified index.
|===

== Transactions Exceptions

[cols="20%,80%", width="100%"]
|===
|Exception	|Description
|`IGN-TX-1`|Failed to create a transaction state storage.
|`IGN-TX-2`|Failed to destroy the transaction state storage.
|`IGN-TX-3`|Failed to work with the transaction state storage.
|`IGN-TX-4`|Transaction state storage is stopped when a different operation is planned.
|===