Package com.surrealdb

Class ServerException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.surrealdb.SurrealException

com.surrealdb.ServerException

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AlreadyExistsException, ConfigurationException, InternalException, NotAllowedException, NotFoundException, QueryException, SerializationException, ThrownException, ValidationException

public class ServerException
extends SurrealException

Base class for all exceptions originating from the SurrealDB server.

Carries structured error information: a machine-readable kind, optional details using the {kind, details?} wire format, and an optional typed cause chain.

Details follow the internally-tagged format where each detail object has a "kind" field and an optional "details" field:

• Unit variant: {"kind": "Parse"}
• Newtype variant: {"kind": "Auth", "details": {"kind": "TokenExpired"}}
• Struct variant: {"kind": "Table", "details": {"name": "users"}}

For backward compatibility with older servers, the legacy externally-tagged format ("Parse", {"Auth": "TokenExpired"}, {"Table": {"name": "users"}}) is also supported by all detail helpers.

Specific error kinds are represented by subclasses (e.g. NotAllowedException, NotFoundException). When the server returns an unknown kind, a plain ServerException is used (not InternalException) to preserve forward compatibility.

See Also:

• ErrorKind
• Serialized Form

Method Summary

Modifier and Type	Method	Description
ServerException	findCause(ErrorKind kind)	Finds the first error in the cause chain (including this error) that has the given ErrorKind.
ServerException	findCause(String kind)	Finds the first error in the cause chain (including this error) that has the given kind.
Object	getDetails()	Returns the optional structured details for this error.
String	getKind()	Returns the machine-readable error kind string (e.g.
ErrorKind	getKindEnum()	Returns the error kind as an enum for type-safe matching.
ServerException	getServerCause()	Returns the typed server-side cause of this error, if any.
boolean	hasKind(ErrorKind kind)	Checks whether this error or any error in its cause chain has the given ErrorKind.
boolean	hasKind(String kind)	Checks whether this error or any error in its cause chain has the given kind.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Details

getKind

public String getKind()

Returns the machine-readable error kind string (e.g. "NotAllowed"). For unknown kinds this is the wire string; otherwise it matches getKindEnum().getRaw().

Returns:

the error kind string, never null

getKindEnum

public ErrorKind getKindEnum()

Returns the error kind as an enum for type-safe matching. Unknown kinds from newer servers map to ErrorKind.UNKNOWN; the raw string is in getKind().

Returns:

the error kind enum, never null

getDetails

public Object getDetails()

Returns the optional structured details for this error.

Details use the {kind, details?} wire format. The value is either:

• null -- no details
• a Map<String, Object> with a "kind" key and optional "details" key (new internally-tagged format)
• a String -- a unit variant in the legacy format (e.g. "Parse")
• a Map<String, Object> without "kind" -- legacy externally-tagged format

Prefer the typed convenience getters on subclasses (e.g. NotFoundException.getTableName()) over inspecting details directly.

Returns:

the details object, or null

getServerCause

public ServerException getServerCause()

Returns the typed server-side cause of this error, if any.

This is equivalent to calling Throwable.getCause() and casting to ServerException, but avoids the cast.

Returns:

the server cause, or null

hasKind

public boolean hasKind(String kind)

Checks whether this error or any error in its cause chain has the given kind.

Parameters:

kind - the kind to look for

Returns:

true if any error in the chain matches

hasKind

public boolean hasKind(ErrorKind kind)

Checks whether this error or any error in its cause chain has the given ErrorKind.

findCause

public ServerException findCause(String kind)

Finds the first error in the cause chain (including this error) that has the given kind.

Parameters:

kind - the kind to look for

Returns:

the matching ServerException, or null

findCause

public ServerException findCause(ErrorKind kind)

Finds the first error in the cause chain (including this error) that has the given ErrorKind.