Errors

Every failed operation raises an error with four fields:

Field	Meaning
code	One of the 33 stable strings below, identical in every SDK
category	One of four kinds, each with a section below
message	What happened in this occurrence
action	What a program or person should do for this occurrence

The tables give each code’s general action. A conflict is returned as a value from sync, without raising an exception. The quickstart shows conflict resolution.

Options and calls use Python spellings. Each language’s reference gives its own spellings.

Caller errors

The call cannot succeed as made. Correct the argument, statement, option or call order. Retrying unchanged fails again.

Code	Condition	Action
analytical_engine_error	The analytical engine refused the statement: an unknown column, a function the build lacks, or a binding count that does not match.	Correct the SQL or bindings and retry.
connection_closed	The connection was closed before the call.	Open another connection and retry.
database_closed	The database was closed before the call.	Open the database again before using it.
encryption_key_required	The remote is encrypted and the database was opened without its key.	Supply the encryption key in OpenOptions.
invalid_argument	An argument is outside its domain: a path, an option value, a binding, or an engine name.	Correct the argument and retry.
invalid_state	The call is invalid in the owner’s current state. A transaction remains open, a transaction context was reused, or a remote remains in use.	Finish or close what the message names, then retry.
license_required	Database creation needs an accepted license key after the machine’s 30-day trial ends. Creation also needs one if the trial anchor is unreadable or more than one day in the future. Existing databases keep opening.	Get a license key at https://potluckdb.com/pricing or, with a company license, claim yours at https://account.potluckdb.com/key and supply it through the license key open option, POTLUCKDB_LICENSE_KEY, or the license-key file in the potluckdb configuration directory.
local_budget_exceeded	The local store has reached local_budget_bytes and cannot admit the write.	Raise OpenOptions.local_budget_bytes or synchronize pending writes.
local_budget_too_small	local_budget_bytes is below the minimum the local store needs.	Raise OpenOptions.local_budget_bytes.
read_in_execute	execute received a statement that reads.	Use query for this statement.
read_only_snapshot	A mutation was attempted on an exact-revision snapshot.	Run the mutation on a writable Database.
remote_closed	The remote was closed while an owner still uses it.	Open a new Remote and retry.
remote_required	Synchronization or conflict resolution was requested on a database opened without a remote.	Open the database with a Remote before synchronizing.
result_limit_exceeded	The result holds more rows than the connection’s maximum_rows.	Add a SQL LIMIT or raise ConnectionOptions.maximum_rows.
snapshot_closed	The snapshot was closed before the call.	Open the revision again before querying it.
sqlite_constraint	SQLite reported the structured primary result code 19 (SQLITE_CONSTRAINT). The statement violates a primary-key, unique, not-null, check, foreign-key, trigger or other SQLite constraint.	Inspect the transaction state and correct the constraint violation before retrying.
sqlite_error	SQLite refused the statement with an error other than constraint, busy or locked. Examples include a syntax error or unbindable value.	Correct the SQL or bindings and retry.
transaction_control_sql	The statement is BEGIN, COMMIT, ROLLBACK, SAVEPOINT or RELEASE, which potluckdb manages itself.	Use transaction() so potluckdb can manage commit and rollback.
unsafe_integer	JavaScript SDKs only: a SQL integer beyond ±2^53 was read without readBigInts. A number cannot represent it exactly.	Open with readBigInts: true to receive bigints.
write_in_query	query received a statement that writes.	Use execute for this statement.

Temporary errors

A lock, storage outage or full disk is expected to clear. The same call succeeds later. Automatic synchronization retries on its own.

Code	Condition	Action
database_busy	Another connection held the database lock past the connection’s timeout, or a synchronization running on another thread held the database. The call ran nothing.	Retry after the competing transaction ends; raise ConnectionOptions.timeout_ms if it recurs.
local_storage_full	The device’s storage is full.	Free local space or raise the local budget, then close and reopen the database and retry.
temporarily_unavailable	The remote or local store did not answer. The condition is expected to clear.	Retry after storage is available; automatic synchronization retries on its own.

Permanent errors

Change the data or deployment before retrying. Examples include a retired revision, wrong encryption key or missing library.

Code	Condition	Action
analytical_engine_unavailable	No analytical engine can be loaded here: the analytics package is not installed and no library is named.	Install the analytics package or name a library in OpenOptions.analytical_engine.
bucket_not_found	The remote’s bucket or container does not exist.	Create the bucket or container, or correct the name the remote was configured with.
data_missing	A piece the revision refers to is absent from the remote.	Restore the missing retained data or open another revision.
integrity_failure	An authenticated record failed verification, or two databases claim one identity.	Preserve the data and investigate the reported identity.
revision_retired	The revision requested, or the one a database or snapshot reads its pieces from, has been collected by retention.	Open a revision that is still retained; for a database, synchronize, then retry the statement.
storage_library_unavailable	The storage library that reaches storage services is not on this machine. A directory remote needs none.	Ship libpotluckdb_storage beside the program, or set POTLUCKDB_STORAGE_LIBRARY to one already on this machine.
unsupported_format	The remote or the local store was written in a format this release does not read.	Use a potluckdb version that supports this data format.
unsupported_storage	The storage service does not enforce the conditional writes that a database depends on. It accepted creation of an existing object or replacement after its version changed, or reported the condition as unimplemented. potluckdb checks this before creating a database.	Place the database on a store that enforces conditional writes, such as one the before-production page lists.
wrong_key_or_corrupt	The encryption key cannot decrypt the remote, or the data is corrupt.	Verify the encryption key and remote data before retrying.

Internal errors

A defect in potluckdb. The message is the report.

Code	Condition	Action
internal_failure	A defect in potluckdb.	Preserve the error details and report this failure.

This page lists every error code that an SDK can raise. The documentation generator reads the same error inventory that the SDKs use.