Error handling

The Java SDK provides a structured exception hierarchy for handling errors from the database and SDK. All exceptions extend SurrealException, which is an unchecked exception. Server-returned errors are represented as ServerException subclasses with typed error details.

API References

Exception hierarchy

SurrealException is the base class for all exceptions thrown by the SDK. It extends RuntimeException, so exceptions are unchecked. ServerException extends SurrealException and represents errors returned by the SurrealDB server. Specific exception types extend ServerException for common error categories.

• SurrealException — base for all SDK errors

  • ServerException — base for server-returned errors

    • NotFoundException — resource not found

    • NotAllowedException — operation not permitted

    • QueryException — query execution failed

    • AlreadyExistsException — resource already exists

Catching server errors

All server errors are ServerException subclasses. Catch specific exceptions first for targeted handling, then fall back to ServerException for unexpected server errors.

try {
    db.query("SELECT * FROM protected_table");
} catch (NotAllowedException e) {
    System.err.println("Permission denied: " + e.getMessage());
} catch (QueryException e) {
    System.err.println("Query failed: " + e.getMessage());
} catch (ServerException e) {
    System.err.println("Server error: " + e.getMessage());
}

Inspecting error details

ServerException provides methods for inspecting the error returned by the server.

• .getKind() — returns the error kind as a String

• .getKindEnum() — returns the error kind as an ErrorKind enum value

• .getDetails() — returns additional error details

The ErrorKind enum includes: VALIDATION, CONFIGURATION, THROWN, QUERY, SERIALIZATION, NOT_ALLOWED, NOT_FOUND, ALREADY_EXISTS, CONNECTION, INTERNAL, and UNKNOWN.

try {
    db.query("INVALID QUERY");
} catch (ServerException e) {
    ErrorKind kind = e.getKindEnum();
    String details = e.getDetails();
    System.err.println(kind + ": " + details);
}

Traversing error chains

Server errors can have nested causes. ServerException provides methods for walking the cause chain to find a specific error type.

• .getServerCause() — returns the underlying ServerException cause, if any

• .hasKind(kind) — checks whether this error or any cause matches the given ErrorKind

• .findCause(kind) — searches the cause chain and returns the first ServerException matching the given ErrorKind

try {
    db.query("SELECT * FROM users");
} catch (ServerException e) {
    if (e.hasKind(ErrorKind.NOT_ALLOWED)) {
        ServerException cause = e.findCause(ErrorKind.NOT_ALLOWED);
        System.err.println("Permission error: " + cause.getDetails());
    }
}

Handling specific error types

Specific exception subclasses expose additional context about the error.

NotFoundException provides .getTableName() and .getRecordId() to identify the missing resource.

try {
    Optional<Value> user = db.select(new RecordId("users", "nonexistent"));
} catch (NotFoundException e) {
    System.err.println("Table: " + e.getTableName());
    System.err.println("Record: " + e.getRecordId());
}

NotAllowedException provides .isTokenExpired() and .isInvalidAuth() to distinguish authentication failures.

try {
    db.query("SELECT * FROM protected");
} catch (NotAllowedException e) {
    if (e.isTokenExpired()) {
        System.err.println("Token expired, re-authenticate");
    } else if (e.isInvalidAuth()) {
        System.err.println("Invalid credentials");
    }
}

QueryException provides .isTimedOut() and .isCancelled() to identify query lifecycle issues.

try {
    db.query("SELECT * FROM large_table");
} catch (QueryException e) {
    if (e.isTimedOut()) {
        System.err.println("Query timed out");
    } else if (e.isCancelled()) {
        System.err.println("Query was cancelled");
    }
}

Learn more

• Errors API reference for complete exception class documentation

• Connecting to SurrealDB for connection error scenarios

• Authentication for authentication error scenarios

• SurrealQL THROW for throwing custom errors from queries