Error Codes Reference¶

This page documents all SQLSTATE error codes that RockLake may return to clients over the PostgreSQL wire protocol. SQLSTATE codes are the standard mechanism for programmatic error handling — your application code should match on these codes, NOT on error message strings. Error messages are human-readable descriptions intended for logs and debugging; they may change between RockLake versions without notice. SQLSTATE codes are stable across versions and safe for programmatic use.

Each code consists of five characters: two characters for the error class (the broad category) and three characters for the specific condition within that class. For example, 42P01 belongs to class 42 (Syntax Error or Access Rule Violation) with specific condition P01 (Undefined Table).

Error Code Index¶

Class 00 — Successful Completion¶

00000: successful_completion¶

The operation completed without errors.

Class 08 — Connection Exception¶

Connection errors indicate problems with the network connection between the client and RockLake.

08000: connection_exception¶

A general connection error that does not fit a more specific category.

08003: connection_does_not_exist¶

The client is attempting to use a connection that has been closed or was never properly established.

08006: connection_failure¶

A network error occurred during an operation. The connection is no longer usable.

Class 0A — Feature Not Supported¶

0A000: feature_not_supported¶

The requested operation or feature is not supported by this version of RockLake.

Class 22 — Data Exception¶

22023: invalid_parameter_value¶

A parameter provided by the client falls outside the valid range.

Class 25 — Invalid Transaction State¶

25001: active_sql_transaction¶

An operation was attempted that cannot be performed while a transaction is in progress.

25006: read_only_sql_transaction¶

A write operation was attempted on a connection or instance that is configured as read-only.

Class 3F — Invalid Schema Name¶

3F000: invalid_schema_name¶

A referenced schema does not exist at the requested snapshot.

Class 42 — Syntax Error or Access Rule Violation¶

The most common error class in RockLake. These errors indicate that the SQL statement is either not recognized or references objects that do not exist.

42000: syntax_error_or_access_rule_violation¶

General catch-all for class 42 errors that do not fit a more specific code.

42601: syntax_error¶

The SQL statement was not recognized by RockLake's bounded SQL classifier. This is the most frequently encountered error for clients sending arbitrary SQL.

Important: This error does NOT mean the SQL is syntactically invalid in general — it means RockLake specifically does not handle this statement pattern.

42P01: undefined_table¶

A referenced table does not exist at the requested snapshot.

42P06: duplicate_schema¶

Attempted to create a schema with a name that already exists.

42P07: duplicate_table¶

Attempted to create a table with a name that already exists in the target schema.

42703: undefined_column¶

A referenced column does not exist in the target table at the requested snapshot.

42710: duplicate_object¶

A generic duplicate object error for entities other than schemas and tables (views, macros, types, sequences).

Class 57 — Operator Intervention¶

57P04: writer_fenced¶

The current writer has been fenced (invalidated) because another writer started with a higher epoch. This is the expected behavior in deployments where a new instance replaces an old one.

Important: Once fenced, a writer NEVER recovers. Do not retry on the same connection. Establish a new connection (which will connect to the new writer).

Class 58 — System Error (External)¶

58000: system_error¶

An error occurred in the underlying object storage system. RockLake could not complete the operation due to an infrastructure issue.

Subcauses (included in error detail):

Class XX — Internal Error¶

XX000: internal_error¶

An unexpected internal error occurred. This indicates a bug in RockLake or data corruption.

If you see XX000 errors repeatedly:

1. Check RockLake version matches the catalog format version
2. Run the verify tool (see Operations: Verify & Repair)
3. Report the issue on GitHub with full error output

Error Handling Best Practices¶

For Client Applications¶

import psycopg2

try:
    cursor.execute(sql)
except psycopg2.errors.SyntaxError:          # 42601
    # Statement not supported — check SQL format
    pass
except psycopg2.errors.UndefinedTable:        # 42P01
    # Table doesn't exist at this snapshot
    pass
except psycopg2.errors.ReadOnlySqlTransaction: # 25006
    # Connected to read-only instance
    pass
except psycopg2.errors.OperationalError as e:
    if e.pgcode == '57P04':
        # Writer fenced — reconnect to new writer
        reconnect()
    elif e.pgcode == '58000':
        # Storage error — retry with backoff
        retry_with_backoff()
    else:
        raise

Retry Logic¶

Idempotency¶

For operations that may fail mid-execution (connection drops after commit but before response):

1. Query the catalog state to check if the operation already succeeded
2. If the object already exists in the expected state, treat as success
3. If not, retry the operation

This is particularly important for 08006 (connection_failure) where the commit may have succeeded but the response was lost.

Further Reading¶

• Supported SQL — What SQL statements RockLake accepts
• Internals: SQLSTATE Mapping — How internal errors map to SQLSTATE codes
• Operations: Troubleshooting — Diagnosing common error scenarios