# Database diagnostics

<!-- Generated by docs/modules/diagnostics from the package catalogs. Write a guide in docs/diagnostics/<CODE>.md instead of editing this file. -->

Each Database error has a stable `code`. Its `docs` link opens the page of that code. This page lists all 70 codes, and [All diagnostics](https://vitehub.dev/docs/reference/diagnostics) lists every primitive.

## Runtime errors

| Code | What happened |
| --- | --- |
| [`DATABASE_CHUNK_INVALID_COUNT`](https://vitehub.dev/docs/database/diagnostics/database_chunk_invalid_count) | chunkParameters() needs `<name>` to be an integer of \<min\> or more, not \<value\>. |
| [`DATABASE_CHUNK_VALUE_TOO_LARGE`](https://vitehub.dev/docs/database/diagnostics/database_chunk_value_too_large) | chunkParameters() cannot fit one value: it takes \<per\> bound parameters and the statement has \<reserved\> more, over the limit of \<limit\>. |
| [`DATABASE_D1_INVALID_RESPONSE`](https://vitehub.dev/docs/database/diagnostics/database_d1_invalid_response) | Cloudflare D1 returned an invalid response shape, such as a different number of results than the number of queries or malformed rows. |
| [`DATABASE_D1_REQUEST_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_d1_request_failed) | Cloudflare D1 \<label\> failed with HTTP \<status\>\<value\> |
| [`DATABASE_D1_STATEMENT_TOO_LONG`](https://vitehub.dev/docs/database/diagnostics/database_d1_statement_too_long) | The SQL statement is \<bytes\> bytes. Cloudflare D1 accepts statements of at most \<limit\> bytes. |
| [`DATABASE_D1_TOO_MANY_PARAMETERS`](https://vitehub.dev/docs/database/diagnostics/database_d1_too_many_parameters) | The query binds \<count\> parameters. Cloudflare D1 accepts at most \<limit\> bound parameters per query. |
| [`DATABASE_D1_VALUE_TOO_LARGE`](https://vitehub.dev/docs/database/diagnostics/database_d1_value_too_large) | A bound value is \<bytes\> bytes. Cloudflare D1 accepts strings and BLOBs of at most \<limit\> bytes. |

## Configuration errors

| Code | What happened |
| --- | --- |
| [`DATABASE_DISABLED`](https://vitehub.dev/docs/database/diagnostics/database_disabled) (guide) | Database is not configured in this runtime. |
| [`DATABASE_INVALID_D1_HTTP_URL`](https://vitehub.dev/docs/database/diagnostics/database_invalid_d1_http_url) | `cloudflare.http.url` of the database "\<database\>" is not an HTTP or HTTPS URL. |
| [`DATABASE_MISSING_CONNECTION`](https://vitehub.dev/docs/database/diagnostics/database_missing_connection) | The database "\<database\>" has no connection. It needs \<needs\>. |
| [`DATABASE_MISSING_D1_HTTP_CONFIG`](https://vitehub.dev/docs/database/diagnostics/database_missing_d1_http_config) | The database "\<database\>" uses D1 HTTP and needs \<missing\> at runtime. |
| [`DATABASE_NAME_REQUIRED`](https://vitehub.dev/docs/database/diagnostics/database_name_required) | `useDatabase()` without a name returns the default or only database, but the app has several and none is named "default": \<choices\>. |
| [`DATABASE_NO_D1_BINDING`](https://vitehub.dev/docs/database/diagnostics/database_no_d1_binding) | The database "\<database\>" has no Cloudflare D1 binding in this runtime. |
| [`DATABASE_NOT_CONNECTED`](https://vitehub.dev/docs/database/diagnostics/database_not_connected) | The database "\<database\>" found no connection. It looked for \<looked\>. |
| [`DATABASE_NOT_FOUND`](https://vitehub.dev/docs/database/diagnostics/database_not_found) (guide) | The database "\<database\>" is not configured.\<value\> |
| [`DATABASE_PGLITE_NOT_INSTALLED`](https://vitehub.dev/docs/database/diagnostics/database_pglite_not_installed) | The database "\<database\>" has no `connection.url` or PG* variables, so development runs it on PGlite, but the app cannot load `@electric-sql/pglite`. |
| [`DATABASE_UNSUPPORTED_URL`](https://vitehub.dev/docs/database/diagnostics/database_unsupported_url) | The database "\<database\>" cannot connect to \<value\>. |
| [`DATABASE_URL_VARIABLE_IGNORED`](https://vitehub.dev/docs/database/diagnostics/database_url_variable_ignored) | The database "\<database\>" has no `connection`, so it uses the local SQLite file \<file\>. `<variable>` is set, but a Database Definition does not read it. |

## Build errors

| Code | What happened |
| --- | --- |
| [`DATABASE_BINDING_CONFLICT`](https://vitehub.dev/docs/database/diagnostics/database_binding_conflict) | \<first\> and \<second\> use the same Cloudflare \<kind\> binding "\<binding\>". |
| [`DATABASE_DUPLICATE_DEFINITION`](https://vitehub.dev/docs/database/diagnostics/database_duplicate_definition) | \<value\>\<files\> |
| [`DATABASE_DUPLICATE_TABLE`](https://vitehub.dev/docs/database/diagnostics/database_duplicate_table) | The database "\<database\>" has two \<kind\>s named "\<name\>":\<value\> |
| [`DATABASE_INVALID_CONTRIBUTION`](https://vitehub.dev/docs/database/diagnostics/database_invalid_contribution) | See the page of the code. |
| [`DATABASE_INVALID_CONTRIBUTION_TARGET`](https://vitehub.dev/docs/database/diagnostics/database_invalid_contribution_target) | See the page of the code. |
| [`DATABASE_INVALID_RELATIONS`](https://vitehub.dev/docs/database/diagnostics/database_invalid_relations) | The relation "\<field\>" of the database "\<database\>" targets the table "\<table\>" |
| [`DATABASE_INVALID_SCHEMA_EXPORT`](https://vitehub.dev/docs/database/diagnostics/database_invalid_schema_export) | The Database Definition "\<handler\>" must default export `defineDatabase({ schema })` with a schema object. |
| [`DATABASE_LAYER_OPTIONS_CONFLICT`](https://vitehub.dev/docs/database/diagnostics/database_layer_options_conflict) | \<problem\>\<files\> |
| [`DATABASE_LAYER_TABLE_CONFLICT`](https://vitehub.dev/docs/database/diagnostics/database_layer_table_conflict) | More than one Nuxt layer declares the table "\<table\>" in the database "\<database\>":\<files\> |
| [`DATABASE_LEGACY_CONFIG_FILE`](https://vitehub.dev/docs/database/diagnostics/database_legacy_config_file) | "\<file\>" uses the former Database file layout. The Database "\<name\>" is now `server/databases/<name>.ts` or `server/databases/<name>/index.ts`. |
| [`DATABASE_MIGRATIONS_OLD_LAYOUT`](https://vitehub.dev/docs/database/diagnostics/database_migrations_old_layout) | \<value\>\<dir\> use the layout of Drizzle Kit 0.x, with `meta/_journal.json`. Drizzle Kit 1.0 and ViteHub read one `<timestamp>_<name>/migration.sql` folder per migration. |
| [`DATABASE_MISSING_D1_RESOURCE`](https://vitehub.dev/docs/database/diagnostics/database_missing_d1_resource) | Cloudflare D1 output needs \<missing\> for \<databases\>. |
| [`DATABASE_MIXED_DEFINITIONS`](https://vitehub.dev/docs/database/diagnostics/database_mixed_definitions) | `src/database.ts` defines the default Database, so other Databases cannot use the Vite form beside it.\<files\> |
| [`DATABASE_NAME_MISMATCH`](https://vitehub.dev/docs/database/diagnostics/database_name_mismatch) | The Database Definition "\<file\>" must set `name: <name>` to match its file name. |
| [`DATABASE_OPAQUE_CLOUDFLARE_CONFIG`](https://vitehub.dev/docs/database/diagnostics/database_opaque_cloudflare_config) | Cloudflare D1 output needs a literal `cloudflare` object for \<databases\>. |
| [`DATABASE_PGLITE_IN_BUILD`](https://vitehub.dev/docs/database/diagnostics/database_pglite_in_build) | These Postgres Databases set `driver: "pglite"`: \<databases\>. PGlite keeps its data in a local folder of one process, so a production build does not include it. |
| [`DATABASE_PROVISION_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_provision_failed) | Cloudflare returned an invalid D1 database list during provisioning. |
| [`DATABASE_RESERVED_SCHEMA_KEY`](https://vitehub.dev/docs/database/diagnostics/database_reserved_schema_key) | \<owner\> uses the reserved schema key "\<key\>". |
| [`DATABASE_SCHEMA_LOAD_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_schema_load_failed) | \<source\> could not load: \<problem\> |
| [`DATABASE_UNKNOWN_DRIVER`](https://vitehub.dev/docs/database/diagnostics/database_unknown_driver) | `database.driver` \<driver\> is not a Database driver. The only driver of the `database` option is "cloudflare". |
| [`DATABASE_WRANGLER_BINDING_CONFLICT`](https://vitehub.dev/docs/database/diagnostics/database_wrangler_binding_conflict) | The D1 binding "\<binding\>"\<scope\> is declared by ViteHub and by the project's Wrangler config with a different \<field\>: \<generated\> and \<project\>. |

## Migration errors

| Code | What happened |
| --- | --- |
| [`DATABASE_D1_MIGRATION_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_d1_migration_failed) | D1 migration failed for the database "\<database\>". \<problem\> |
| [`DATABASE_D1_MIGRATION_INVALID`](https://vitehub.dev/docs/database/diagnostics/database_d1_migration_invalid) | D1 migration history is invalid. \<problem\> |
| [`DATABASE_MIGRATE_ON_DEPLOY_UNSUPPORTED`](https://vitehub.dev/docs/database/diagnostics/database_migrate_on_deploy_unsupported) | `database.migrateOnDeploy` applies migrations only to Cloudflare D1 bindings, with `wrangler d1 migrations apply` before `wrangler deploy`\<value\>. \<problem\> |
| [`DATABASE_MIGRATE_ON_START_UNSUPPORTED`](https://vitehub.dev/docs/database/diagnostics/database_migrate_on_start_unsupported) | `database.migrateOnStart` and `ensureMigrations()` apply migrations only to local SQLite files and Postgres in a Node server\<value\>. \<problem\> |
| [`DATABASE_MIGRATION_BACKUP_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_migration_backup_failed) | ViteHub cannot back up the database "\<database\>" to "\<target\>" before its pending migrations: \<problem\> The server applied no migration. |
| [`DATABASE_MIGRATION_BACKUP_UNSUPPORTED`](https://vitehub.dev/docs/database/diagnostics/database_migration_backup_unsupported) | `migrateOnStart.backup` copies only local SQLite files\<value\>. \<problem\> |
| [`DATABASE_MIGRATION_CHECK_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_migration_check_failed) | ViteHub cannot read the pending migrations of the database "\<database\>". \<problem\> |
| [`DATABASE_MIGRATION_DATA_LOSS`](https://vitehub.dev/docs/database/diagnostics/database_migration_data_loss) | Pending migrations of the database "\<database\>" lose data:\<statements\> |
| [`DATABASE_MIGRATION_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_migration_failed) | The migration "\<migration\>" of the database "\<database\>" failed: \<problem\> The database rolled back every pending migration of this run. |

## Setup errors

| Code | What happened |
| --- | --- |
| [`DATABASE_D1_MIGRATIONS_DIR_INVALID`](https://vitehub.dev/docs/database/diagnostics/database_d1_migrations_dir_invalid) | D1 migrations_dir must be a relative directory inside Nitro's server output. |
| [`DATABASE_D1_MIGRATIONS_DIR_OVERLAP`](https://vitehub.dev/docs/database/diagnostics/database_d1_migrations_dir_overlap) | D1 migration directories overlap for bindings \<first\> and \<second\>; configure an exclusive migrations_dir for each binding. |
| [`DATABASE_NUXT_CONTENT_D1_MISSING`](https://vitehub.dev/docs/database/diagnostics/database_nuxt_content_d1_missing) | Nuxt Content on Cloudflare requires an explicit content.database configuration or a complete Wrangler D1 binding named DB. |
| [`DATABASE_POSTGRES_DRIVER_MISSING`](https://vitehub.dev/docs/database/diagnostics/database_postgres_driver_missing) | Cannot load the `<name>` package from the project. Install it, for example with `pnpm add <name>`. |

## Definition errors

| Code | What happened |
| --- | --- |
| [`DATABASE_DRIZZLE_OPTION_REMOVED`](https://vitehub.dev/docs/database/diagnostics/database_drizzle_option_removed) | `defineDatabase()` has no `drizzle` option. Drizzle 1.0 removed the database `casing` option. |
| [`DATABASE_INVALID_DIALECT`](https://vitehub.dev/docs/database/diagnostics/database_invalid_dialect) | The Database Definition "\<file\>" must set `dialect` to the string literal "sqlite" or "postgresql". |
| [`DATABASE_INVALID_DRIVER`](https://vitehub.dev/docs/database/diagnostics/database_invalid_driver) | The Database Definition "\<file\>" must set `driver` to the string literal "node-postgres" or "pglite". |
| [`DATABASE_INVALID_NAME`](https://vitehub.dev/docs/database/diagnostics/database_invalid_name) | `defineDatabase().name` must be a normalized path of letters, numbers, dots, underscores, or dashes. |
| [`DATABASE_INVALID_OPTIONS`](https://vitehub.dev/docs/database/diagnostics/database_invalid_options) | `<path>` must be a plain object. |
| [`DATABASE_INVALID_REMOTE`](https://vitehub.dev/docs/database/diagnostics/database_invalid_remote) | `defineDatabase().remote` must be `true` or `false`. |
| [`DATABASE_REMOTE_CONFLICT`](https://vitehub.dev/docs/database/diagnostics/database_remote_conflict) | The database "\<database\>" sets `remote: false`, but `cloudflare.http` sends `vite dev` queries to the remote D1 database. |
| [`DATABASE_UNKNOWN_OPTION`](https://vitehub.dev/docs/database/diagnostics/database_unknown_option) | `defineDatabase()` with `dialect: "postgresql"` does not support `<option>`. |

## SQL and drop errors

| Code | What happened |
| --- | --- |
| [`DATABASE_DROP_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_drop_failed) (guide) | `vitehub database <command>` cannot drop the tables of the database "\<database\>". \<problem\> |
| [`DATABASE_DROP_NOT_CONFIRMED`](https://vitehub.dev/docs/database/diagnostics/database_drop_not_confirmed) (guide) | `vitehub database <command>` drops every table of the database "\<database\>" and was not confirmed. |
| [`DATABASE_SQL_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_sql_failed) (guide) | ViteHub cannot run the SQL on the database "\<database\>". \<problem\> |

## Export errors

| Code | What happened |
| --- | --- |
| [`DATABASE_EXPORT_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_export_failed) | ViteHub cannot export the database "\<database\>". \<problem\> |

## Generate errors

| Code | What happened |
| --- | --- |
| [`DATABASE_GENERATE_AMBIGUOUS_CHANGE`](https://vitehub.dev/docs/database/diagnostics/database_generate_ambiguous_change) | The Definitions of the database "\<database\>" add a column or table and remove another one, and Drizzle Kit cannot tell whether the new one is a rename. Without a terminal, `vitehub database generate` cannot ask, so it wrote no migration.\<value\> |

## Idempotency errors

| Code | What happened |
| --- | --- |
| [`DATABASE_IDEMPOTENCY_IN_PROGRESS`](https://vitehub.dev/docs/database/diagnostics/database_idempotency_in_progress) | Another call with the key \<key\> is running. |
| [`DATABASE_IDEMPOTENCY_INVALID_OPTIONS`](https://vitehub.dev/docs/database/diagnostics/database_idempotency_invalid_options) | `<option>` of `withIdempotency()` must be a positive number of seconds. |

## Seed errors

| Code | What happened |
| --- | --- |
| [`DATABASE_SEED_FAILED`](https://vitehub.dev/docs/database/diagnostics/database_seed_failed) | ViteHub cannot seed the database "\<database\>". \<problem\> |
| [`DATABASE_SEED_NOT_FOUND`](https://vitehub.dev/docs/database/diagnostics/database_seed_not_found) | The database "\<database\>" has no seed file. ViteHub looks for \<file\>. |
| [`DATABASE_SEED_PENDING_MIGRATIONS`](https://vitehub.dev/docs/database/diagnostics/database_seed_pending_migrations) | The database "\<database\>" has pending migrations, so the seed would not see the current tables:\<migrations\> |

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/database.md)
- [Get started](https://vitehub.dev/raw/docs/database/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/database/configure.md)
- [Server API](https://vitehub.dev/raw/docs/database/server-api.md)
- [Agent capability](https://vitehub.dev/raw/docs/database/agent-capability.md)
- [Hosts](https://vitehub.dev/raw/docs/database/hosts.md)
- [Limits and errors](https://vitehub.dev/raw/docs/database/limits-and-errors.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
