Errors

The Java SDK uses a hierarchy of exceptions rooted at SurrealException. Server-returned errors are represented by ServerException and its subclasses, which provide structured access to error details, kinds, and cause chains.

Source: surrealdb.java

Exception Hierarchy

• SurrealException (extends RuntimeException)

  • ServerException

    • NotFoundException

    • NotAllowedException

    • QueryException

    • AlreadyExistsException

    • ValidationException

    • ConfigurationException

    • SerializationException

    • InternalException

    • ThrownException

SurrealException

Base exception for all SDK errors. Extends RuntimeException.

All exceptions thrown by the Java SDK are subclasses of SurrealException, making it possible to catch all SDK-related errors with a single catch block.

try {
    db.query("SELECT * FROM users");
} catch (SurrealException e) {
    System.err.println("SDK error: " + e.getMessage());
}

ServerException

Base class for all server-returned errors. Extends SurrealException.

ServerException provides structured access to the error kind, details, and cause chain returned by the server. All specific server error types extend this class.

.getKind()

Returns the error kind as a string.

exception.getKind()

Returns: String

try {
    db.select(Person.class, new RecordId("person", "missing"));
} catch (ServerException e) {
    String kind = e.getKind();
}

.getKindEnum()

Returns the error kind as an ErrorKind enum value.

exception.getKindEnum()

Returns: ErrorKind

try {
    db.query("INVALID QUERY");
} catch (ServerException e) {
    ErrorKind kind = e.getKindEnum();
}

.getDetails()

Returns structured error details provided by the server.

exception.getDetails()

Returns: Object

.getServerCause()

Returns the typed server cause if the error was caused by another server error.

exception.getServerCause()

Returns: ServerException

.hasKind(kind)

Checks if the error or any error in its cause chain matches a specific kind.

exception.hasKind(kind)

Returns: boolean

try {
    db.query("SELECT * FROM protected_table");
} catch (ServerException e) {
    if (e.hasKind(ErrorKind.NOT_ALLOWED)) {
        System.err.println("Permission denied");
    }
}

.findCause(kind)

Finds the first error in the cause chain that matches a specific kind.

exception.findCause(kind)

Returns: ServerException

try {
    db.query("CREATE person SET name = 'Alice'");
} catch (ServerException e) {
    ServerException cause = e.findCause(ErrorKind.ALREADY_EXISTS);
    if (cause != null) {
        System.err.println("Duplicate: " + cause.getMessage());
    }
}

ErrorKind

Enum representing error categories returned by the server.

ErrorKind.fromString(kind)

Converts a string to an ErrorKind enum value. Returns UNKNOWN if the string does not match any known kind.

ErrorKind.fromString(kind)

Returns: ErrorKind

ErrorKind kind = ErrorKind.fromString("NotFound");

NotFoundException

Thrown when a requested resource does not exist. Extends ServerException.

Additional Methods

try {
    db.select(Person.class, new RecordId("person", "nonexistent"));
} catch (NotFoundException e) {
    String table = e.getTableName();
    String record = e.getRecordId();
}

NotAllowedException

Thrown when an operation is not permitted. Extends ServerException.

Additional Methods

try {
    db.query("SELECT * FROM protected_table");
} catch (NotAllowedException e) {
    if (e.isTokenExpired()) {
        db.signin(new RootCredential("root", "root"));
    }
}

QueryException

Thrown when a query fails to execute. Extends ServerException.

Additional Methods

try {
    db.query("SELECT * FROM large_table TIMEOUT 1s");
} catch (QueryException e) {
    if (e.isTimedOut()) {
        System.err.println("Query timed out: " + e.getTimeout());
    }
}

AlreadyExistsException

Thrown when attempting to create a resource that already exists. Extends ServerException.

Additional Methods

try {
    db.create(Person.class, new RecordId("person", "alice"), person);
} catch (AlreadyExistsException e) {
    String recordId = e.getRecordId();
}

ValidationException

Thrown when data validation fails. Extends ServerException. No additional methods.

ConfigurationException

Thrown when there is a configuration error. Extends ServerException. No additional methods.

SerializationException

Thrown when serialization or deserialization fails. Extends ServerException. No additional methods.

InternalException

Thrown for internal server errors. Extends ServerException. No additional methods.

ThrownException

Thrown when a SurrealQL THROW statement is executed. Extends ServerException. No additional methods.

try {
    db.query("THROW 'custom error message'");
} catch (ThrownException e) {
    System.err.println("SurrealQL threw: " + e.getMessage());
}

See Also

• Surreal — Connection and method reference

• Error handling — Error handling concepts and patterns

• SurrealQL THROW — Throwing custom errors from queries