Light
Dark
System
v4latest
v4latest
v3
v2
v1

Errors

Each error in EdgeDB consists of a code, a name, and optionally tags. Errors in EdgeDB can inherit from other errors. This is denoted by matching code prefixes. For example, TransactionConflictError (0x_05_03_01_00) is the parent error for TransactionSerializationError (0x_05_03_01_01) and TransactionDeadlockError (0x_05_03_01_02). The matching prefix here is 0x_05_03_01.

When the EdgeDB client expects a more general error and EdgeDB returns a more specific error that inherits from the general error, the check in the client must take this into account. This can be expressed by the binary and operation or & opeator in most programming languages:

(expected_error_code & server_error_code) == expected_error_code

Note that although it is not explicitly stated in the edb/api/errors.txt file, each inherited error must contain all tags of the parent error. Given that, TransactionSerializationError and TransactionDeadlockError, for example, must contain the SHOULD_RETRY tag that is defined for TransactionConflictError.

Error codes and names as specified in edb/api/errors.txt:

Copy
#
# This source file is part of the EdgeDB open source project.
#
# Copyright 2016-present MagicStack Inc. and the EdgeDB authors.
#
# Licensed 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.
#


####

0x_01_00_00_00   InternalServerError

####

0x_02_00_00_00   UnsupportedFeatureError


####

0x_03_00_00_00   ProtocolError

0x_03_01_00_00   BinaryProtocolError
0x_03_01_00_01   UnsupportedProtocolVersionError
0x_03_01_00_02   TypeSpecNotFoundError
0x_03_01_00_03   UnexpectedMessageError

0x_03_02_00_00   InputDataError
0x_03_02_01_00   ParameterTypeMismatchError
0x_03_02_02_00   StateMismatchError  #SHOULD_RETRY

0x_03_03_00_00   ResultCardinalityMismatchError

0x_03_04_00_00   CapabilityError
0x_03_04_01_00   UnsupportedCapabilityError
0x_03_04_02_00   DisabledCapabilityError


####

0x_04_00_00_00   QueryError

0x_04_01_00_00   InvalidSyntaxError
0x_04_01_01_00   EdgeQLSyntaxError
0x_04_01_02_00   SchemaSyntaxError
0x_04_01_03_00   GraphQLSyntaxError

0x_04_02_00_00   InvalidTypeError
0x_04_02_01_00   InvalidTargetError
0x_04_02_01_01   InvalidLinkTargetError
0x_04_02_01_02   InvalidPropertyTargetError

0x_04_03_00_00   InvalidReferenceError
0x_04_03_00_01   UnknownModuleError
0x_04_03_00_02   UnknownLinkError
0x_04_03_00_03   UnknownPropertyError
0x_04_03_00_04   UnknownUserError
0x_04_03_00_05   UnknownDatabaseError
0x_04_03_00_06   UnknownParameterError

0x_04_04_00_00   SchemaError

0x_04_05_00_00   SchemaDefinitionError

0x_04_05_01_00   InvalidDefinitionError
0x_04_05_01_01   InvalidModuleDefinitionError
0x_04_05_01_02   InvalidLinkDefinitionError
0x_04_05_01_03   InvalidPropertyDefinitionError
0x_04_05_01_04   InvalidUserDefinitionError
0x_04_05_01_05   InvalidDatabaseDefinitionError
0x_04_05_01_06   InvalidOperatorDefinitionError
0x_04_05_01_07   InvalidAliasDefinitionError
0x_04_05_01_08   InvalidFunctionDefinitionError
0x_04_05_01_09   InvalidConstraintDefinitionError
0x_04_05_01_0A   InvalidCastDefinitionError

0x_04_05_02_00   DuplicateDefinitionError
0x_04_05_02_01   DuplicateModuleDefinitionError
0x_04_05_02_02   DuplicateLinkDefinitionError
0x_04_05_02_03   DuplicatePropertyDefinitionError
0x_04_05_02_04   DuplicateUserDefinitionError
0x_04_05_02_05   DuplicateDatabaseDefinitionError
0x_04_05_02_06   DuplicateOperatorDefinitionError
0x_04_05_02_07   DuplicateViewDefinitionError
0x_04_05_02_08   DuplicateFunctionDefinitionError
0x_04_05_02_09   DuplicateConstraintDefinitionError
0x_04_05_02_0A   DuplicateCastDefinitionError
0x_04_05_02_0B   DuplicateMigrationError

####

0x_04_06_00_00   SessionTimeoutError

0x_04_06_01_00   IdleSessionTimeoutError #SHOULD_RETRY

0x_04_06_02_00   QueryTimeoutError

0x_04_06_0A_00   TransactionTimeoutError
0x_04_06_0A_01   IdleTransactionTimeoutError

####

0x_05_00_00_00   ExecutionError

0x_05_01_00_00   InvalidValueError
0x_05_01_00_01   DivisionByZeroError
0x_05_01_00_02   NumericOutOfRangeError
0x_05_01_00_03   AccessPolicyError
0x_05_01_00_04   QueryAssertionError

0x_05_02_00_00   IntegrityError
0x_05_02_00_01   ConstraintViolationError
0x_05_02_00_02   CardinalityViolationError
0x_05_02_00_03   MissingRequiredError

0x_05_03_00_00   TransactionError
0x_05_03_01_00   TransactionConflictError  #SHOULD_RETRY
0x_05_03_01_01   TransactionSerializationError
0x_05_03_01_02   TransactionDeadlockError

0x_05_04_00_00   WatchError


####

0x_06_00_00_00   ConfigurationError


####

0x_07_00_00_00   AccessError

0x_07_01_00_00   AuthenticationError


####

0x_08_00_00_00   AvailabilityError

0x_08_00_00_01   BackendUnavailableError  #SHOULD_RETRY
0x_08_00_00_02   ServerOfflineError  #SHOULD_RECONNECT #SHOULD_RETRY
0x_08_00_00_03   UnknownTenantError  #SHOULD_RECONNECT #SHOULD_RETRY
0x_08_00_00_04   ServerBlockedError

####

0x_09_00_00_00   BackendError

0x_09_00_01_00   UnsupportedBackendFeatureError


####

0x_F0_00_00_00   LogMessage

0x_F0_01_00_00   WarningMessage


#### Suggested errors for EdgeDB clients

0x_FF_00_00_00   ClientError
0x_FF_01_00_00   ClientConnectionError
0x_FF_01_01_00   ClientConnectionFailedError
0x_FF_01_01_01   ClientConnectionFailedTemporarilyError  #SHOULD_RECONNECT #SHOULD_RETRY
0x_FF_01_02_00   ClientConnectionTimeoutError  #SHOULD_RECONNECT #SHOULD_RETRY
0x_FF_01_03_00   ClientConnectionClosedError  #SHOULD_RECONNECT #SHOULD_RETRY

0x_FF_02_00_00   InterfaceError

0x_FF_02_01_00   QueryArgumentError
0x_FF_02_01_01   MissingArgumentError
0x_FF_02_01_02   UnknownArgumentError
0x_FF_02_01_03   InvalidArgumentError

0x_FF_03_00_00   NoDataError

0x_FF_04_00_00   InternalClientError
Light
Dark
System

We use ChatGPT with additional context from our documentation to answer your questions. Not all answers will be accurate. Please join our Discord if you need more help.