Errors

The SDK defines specific error classes for different failure scenarios. All error classes extend the base SurrealError class, allowing you to catch and handle specific error types.

Base Error

SurrealError

Base class for all SDK errors.

Extends: Error

Example:

try {
    await db.select(new RecordId('users', 'john'));
} catch (error) {
    if (error instanceof SurrealError) {
        console.error('SDK error:', error.message);
    }
}

Connection Errors

ConnectionUnavailableError

Thrown when attempting an operation without an active connection.

Message: "You must be connected to a SurrealDB instance before performing this operation"

Example:

const db = new Surreal();

try {
    await db.select(new Table('users')); // Not connected
} catch (error) {
    if (error instanceof ConnectionUnavailableError) {
        console.error('Not connected to database');
        await db.connect('ws://localhost:8000');
    }
}

HttpConnectionError

Thrown when an HTTP connection fails.

Properties:

• status (number) - HTTP status code
• statusText (string) - HTTP status text
• buffer (ArrayBuffer) - Response buffer

Example:

try {
    await db.connect('http://localhost:8000/rpc');
} catch (error) {
    if (error instanceof HttpConnectionError) {
        console.error(`HTTP ${error.status}: ${error.statusText}`);
    }
}

CallTerminatedError

Thrown when a call is terminated because the connection was closed.

Message: "The call has been terminated because the connection was closed"

Example:

try {
    const promise = db.query('SELECT SLEEP(10s)');
    await db.close(); // Close connection while query running
    await promise; // Will throw CallTerminatedError
} catch (error) {
    if (error instanceof CallTerminatedError) {
        console.error('Connection closed during operation');
    }
}

UnexpectedConnectionError

Thrown when an unexpected connection error occurs.

Properties:

• cause (unknown) - The underlying error cause

Example:

try {
    await db.connect('ws://invalid:8000');
} catch (error) {
    if (error instanceof UnexpectedConnectionError) {
        console.error('Connection error:', error.cause);
    }
}

UnsupportedEngineError

Thrown when attempting to use an unsupported or unconfigured engine.

Properties:

• engine (string) - The unsupported engine name

Example:

try {
    await db.connect('custom://localhost:8000');
} catch (error) {
    if (error instanceof UnsupportedEngineError) {
        console.error(`Engine "${error.engine}" is not supported`);
    }
}

Reconnection Errors

ReconnectExhaustionError

Thrown when reconnect attempts have been exhausted.

Message: "The reconnect attempts have been exhausted"

Example:

db.subscribe('error', (error) => {
    if (error instanceof ReconnectExhaustionError) {
        console.error('Failed to reconnect after multiple attempts');
        // Implement custom reconnection logic
    }
});

ReconnectIterationError

Thrown when a reconnect iterator fails to iterate.

Message: "The reconnect iterator failed to iterate"

Response Errors

ResponseError

Thrown when a database query fails with an error response.

Properties:

• code (number) - Error code from the database
• message (string) - Error message from the database

Example:

try {
    await db.query('INVALID QUERY');
} catch (error) {
    if (error instanceof ResponseError) {
        console.error(`Database error [${error.code}]: ${error.message}`);
    }
}

UnexpectedServerResponseError

Thrown when the server returns an unexpected response format.

Properties:

• response (unknown) - The unexpected response received

Example:

try {
    await db.query(complexQuery);
} catch (error) {
    if (error instanceof UnexpectedServerResponseError) {
        console.error('Unexpected response:', error.response);
    }
}

Authentication Errors

AuthenticationError

Thrown when authentication fails.

Message: "Authentication did not succeed"

Properties:

• cause (unknown) - The underlying error cause

Example:

try {
    await db.signin({
        username: 'user',
        password: 'wrongpassword'
    });
} catch (error) {
    if (error instanceof AuthenticationError) {
        console.error('Authentication failed:', error.cause);
    }
}

MissingNamespaceDatabaseError

Thrown when a namespace and/or database is required but not selected.

Message: "There is no namespace and/or database selected"

Example:

const db = new Surreal();
await db.connect('ws://localhost:8000');

try {
    await db.select(new Table('users')); // No namespace/database set
} catch (error) {
    if (error instanceof MissingNamespaceDatabaseError) {
        await db.use({ namespace: 'test', database: 'test' });
    }
}

Live Query Errors

LiveSubscriptionError

Thrown when a live subscription fails to listen.

Message: "Live subscription failed to listen"

Properties:

• cause (unknown) - The underlying error cause

Example:

try {
    const subscription = await db.live(new Table('users'));
} catch (error) {
    if (error instanceof LiveSubscriptionError) {
        console.error('Live query failed:', error.cause);
    }
}

Version Errors

UnsupportedVersionError

Thrown when the connected SurrealDB version is not supported by the SDK.

Properties:

• version (string) - The unsupported version
• minimum (string) - Minimum supported version (inclusive)
• maximum (string) - Maximum supported version (exclusive)

Example:

try {
    await db.connect('ws://localhost:8000', {
        versionCheck: true
    });
} catch (error) {
    if (error instanceof UnsupportedVersionError) {
        console.error(
            `Version ${error.version} not supported. ` +
            `Requires: >= ${error.minimum} < ${error.maximum}`
        );
    }
}

Expression Errors

ExpressionError

Thrown when an expression fails to compile or execute.

Example:

try {
    const invalid = expr(() => {
        throw new Error('Invalid expression');
    });
} catch (error) {
    if (error instanceof ExpressionError) {
        console.error('Expression error:', error.message);
    }
}

PublishError

Thrown when one or more event subscribers throw an error during publication.

Properties:

• causes (unknown[]) - The errors thrown by subscribers
• message (string) - Summary message including the cause messages

Example:

db.subscribe('auth', () => {
    throw new Error('Handler failed');
});
// When the event fires, a PublishError may be emitted

InvalidDateError

Thrown when a parsed date is invalid.

Message: "The provided date is invalid"

Example:

try {
    DateTime.parse('not-a-date');
} catch (error) {
    if (error instanceof InvalidDateError) {
        console.error('Invalid date:', error.message);
    }
}

Feature Errors

UnsupportedFeatureError

Thrown when attempting to use a feature not supported by the configured engine.

Properties:

• feature (Feature) - The unsupported feature

Example:

try {
    // Attempt to use a feature not supported by server
    await db.api().get('/endpoint');
} catch (error) {
    if (error instanceof UnsupportedFeatureError) {
        console.error(`Feature "${error.feature.name}" not supported`);
    }
}

UnavailableFeatureError

Thrown when attempting to use a feature not available in the connected SurrealDB version.

Properties:

• feature (Feature) - The unavailable feature
• version (string) - The connected SurrealDB version

Example:

try {
    await db.connect('http://localhost:8000/rpc'); // HTTP engine
    await db.live(new Table('users')); // Live queries require WebSocket
} catch (error) {
    if (error instanceof UnavailableFeatureError) {
        console.error(`Feature "${error.feature.name}" not available in version ${error.version}`);
    }
}

API Errors

UnsuccessfulApiError

Thrown when a user-defined API call fails.

Properties:

• path (string) - The API path that was invoked
• method (string) - The HTTP method used
• response (ApiResponse) - The error response from the API (includes body?, headers?, status?)
• message (string) - Human-readable message (inherited from Error; includes path, method, and status)

Example:

try {
    await db.api().get('/users/999');
} catch (error) {
    if (error instanceof UnsuccessfulApiError) {
        console.error(`API error: ${error.message}`);
        console.error(`Status: ${error.response.status}`);
    }
}

Session Errors

InvalidSessionError

Thrown when attempting to use an invalid or disposed session.

Properties:

• session (Session) - The invalid session identifier

Example:

const session = await db.newSession();
await session.closeSession();

try {
    await session.select(new Table('users')); // Session closed
} catch (error) {
    if (error instanceof InvalidSessionError) {
        console.error('Session is no longer valid');
    }
}

Error Handling Patterns

Basic Error Handling

try {
    const result = await db.select(new Table('users'));
} catch (error) {
    if (error instanceof SurrealError) {
        // Handle all SDK errors
        console.error('SDK error:', error.message);
    } else {
        // Handle other errors
        console.error('Unexpected error:', error);
    }
}

Specific Error Handling

try {
    await db.connect('ws://localhost:8000');
    await db.use({ namespace: 'test', database: 'test' });
    await db.signin({ username: 'user', password: 'pass' });
} catch (error) {
    if (error instanceof ConnectionUnavailableError) {
        console.error('Cannot connect to database');
    } else if (error instanceof AuthenticationError) {
        console.error('Invalid credentials');
    } else if (error instanceof UnsupportedVersionError) {
        console.error('Database version incompatible');
    } else {
        console.error('Unknown error:', error);
    }
}

Error Recovery

async function executeWithRetry(fn: () => Promise<any>, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            return await fn();
        } catch (error) {
            if (error instanceof ConnectionUnavailableError) {
                // Reconnect and retry
                await db.connect('ws://localhost:8000');
                continue;
            } else if (error instanceof ResponseError && attempt < maxRetries - 1) {
                // Retry on response errors
                continue;
            }
            throw error;
        }
    }
}

const result = await executeWithRetry(() => 
    db.select(new Table('users'))
);

Global Error Handler

db.subscribe('error', (error) => {
    if (error instanceof ReconnectExhaustionError) {
        // Handle reconnection failure
        notifyUser('Connection lost. Please check your network.');
    } else if (error instanceof UnexpectedConnectionError) {
        // Log unexpected errors
        logger.error('Unexpected connection error:', error.cause);
    }
});

Best Practices

1. Catch Specific Errors

Handle specific error types for better error recovery:

// Good: Specific handling
try {
    await operation();
} catch (error) {
    if (error instanceof AuthenticationError) {
        redirectToLogin();
    } else if (error instanceof ConnectionUnavailableError) {
        showConnectionError();
    }
}

// Avoid: Generic handling
try {
    await operation();
} catch (error) {
    console.error(error); // Lost context
}

2. Use Type Guards

TypeScript type guards provide better type safety:

function isConnectionError(error: unknown): error is ConnectionUnavailableError {
    return error instanceof ConnectionUnavailableError;
}

if (isConnectionError(error)) {
    // TypeScript knows error is ConnectionUnavailableError
    await reconnect();
}

3. Log Error Details

Include error details in logs for debugging:

catch (error) {
    if (error instanceof ResponseError) {
        logger.error('Query failed', {
            code: error.code,
            message: error.message,
            query: originalQuery
        });
    }
}

4. Clean Up on Error

Ensure resources are cleaned up even when errors occur:

const session = await db.newSession();
try {
    await session.select(new Table('users'));
} finally {
    await session.closeSession(); // Always clean up
}

See Also

• Core Classes - Classes that may throw errors
• Surreal - Connection methods that may throw errors
• SurrealSession - Session methods that may throw errors

Source: errors.ts