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:

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