API: error codes

SqliteErrorCode is the closed set of values SqliteError.code can take. Every value below is returned on success: false — never as a thrown/rejected error. See Concepts for the result shape.

type SqliteErrorCode =
  | 'INVALID_PARAMS'
  | 'INVALID_NAME'
  | 'DB_NOT_OPEN'
  | 'DB_ALREADY_OPEN'
  | 'OPEN_FAILED'
  | 'CLOSE_FAILED'
  | 'EXECUTE_FAILED'
  | 'QUERY_FAILED'
  | 'VACUUM_FAILED'
  | 'VERSION_FAILED'
  | 'SCHEMA_VERSION_FAILED'
  | 'TRANSACTION_FAILED'
  | 'MIGRATION_FAILED'
  | 'NOT_AVAILABLE'
  | 'UNKNOWN';

Code	Typical cause	Fix
`INVALID_PARAMS`	Missing/extra bind `values`, a numbered/named placeholder, multiple SQL statements in one string, a non-finite `number`, an empty `statements`/`values` array, or `query()` called with write DML that has no `RETURNING`.	Fix the statement/values shape per Usage. Use `run()` for plain writes, `RETURNING` for `query()` on writes.
`INVALID_NAME`	The `database` name contains characters outside `A-Z`, `a-z`, `0-9`, `_`, `-`, or (on Electron) resolves to an invalid on-disk path.	Use a plain alphanumeric/underscore/hyphen name; do not pass a filesystem path as `database`.
`DB_NOT_OPEN`	A call was made against a `database` name that has no open connection.	Call `open()` for that database before any other method.
`DB_ALREADY_OPEN`	`open()` was called again for an already-open database with a different `readonly` value or `directory` than the original call.	Reuse the original `readonly`/`directory`, or `close()` first if you need to reopen with different settings.
`OPEN_FAILED`	The native/wasm layer failed to open the database file (permissions, corruption, storage unavailable).	Inspect `error.details.nativeMessage`; verify the storage location is writable and the file isn't corrupted.
`CLOSE_FAILED`	The native layer failed while closing a connection.	Inspect `error.details.nativeMessage`.
`EXECUTE_FAILED`	A statement passed to `execute()` failed at the SQL level (bad DDL/DML, constraint violation).	Inspect `error.message`/`nativeMessage` for the SQLite error text.
`QUERY_FAILED`	A statement passed to `query()` failed at the SQL level, or on Electron/Web the compact row-decoder failed to reconstruct results.	Inspect `error.message`/`nativeMessage`.
`VACUUM_FAILED`	`VACUUM` failed (commonly: insufficient free disk space, or a transaction still open on the connection).	Ensure no manual transaction is active and enough disk space is available, then retry.
`VERSION_FAILED`	`getVersion()` failed to read the SQLite engine version.	Inspect `error.details.nativeMessage`.
`SCHEMA_VERSION_FAILED`	`getSchemaVersion()` failed to read `PRAGMA user_version`.	Inspect `error.details.nativeMessage`.
`TRANSACTION_FAILED`	`beginTransaction()` called while one is already active; `execute()`/`runBatch()`/`runMany()` called with their default `transaction: true` while a manual transaction is active; or `commitTransaction()`/`rollbackTransaction()` called with none active.	See Transactions — pass `transaction: false` to participate in an existing transaction instead of nesting.
`MIGRATION_FAILED`	A migration entry is malformed, `version` values are duplicated within one `open()` call, `version` is out of the `1..2147483647` range, or a migration statement failed.	See Migrations — check version uniqueness/range and each statement's SQL.
`NOT_AVAILABLE`	SQLite is not available on this platform/runtime — e.g. Electron's `node:sqlite` missing on an older Electron/Node, or the Electron main-process plugin never registered `CapacitorCustomPlatform`.	Call `isAvailable()` before relying on persistent storage; verify Electron plugin registration (see Installation → Electron).
`UNKNOWN`	An unclassified native/bridge failure, including the JS wrapper's own catch-all for an unexpected exception.	Inspect `error.details.nativeMessage` for the underlying platform error.

Reading `error.details`

Every SqliteError.details object includes nativeCode, nativeMessage, and source. Treat any additional keys as platform-specific debugging hints rather than a stable API — they can differ between iOS, Android, Web, and Electron for the same code.

const result = await CapacitorSqlite.open({ database: 'myapp' });
if (!result.success) {
  console.error(result.error.code, result.error.details.nativeMessage);
}

Troubleshooting walks through the most common failure scenarios with these codes in context.