# DATABASE_NOT_FOUND

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

ViteHub throws `DATABASE_NOT_FOUND` when you select a database by a name that has no Database Definition. `error.why` names the database. For `useDatabase()`, it also lists the discovered Database names, or `none` when the app has no Database.

## Why it happens

ViteHub discovers one Database for each Definition. A Named Database gets its name from `server/databases/<name>.ts`, `server/databases/<name>/index.ts`, or `src/<name>.database.ts`. The Default Database is `default`. The error comes from these calls:

- The Agent `db()` Capability with a `database` option. It calls `agentDb.database(name)`, which throws for an unknown name.
- `useDatabase(name)` with an unknown name, including `default` when the app has only Named Databases.
- `useDatabase()` without a name when the app has no Database. With a Default Database or one Named Database, it returns that Database. With several Named Databases and no Default Database, it throws `DATABASE_NAME_REQUIRED`.
- `vitehub database export --database <name>`. The command prints the error and exits with code 1.
- A query through the `db` export or `databases.default` when the app has only Named Databases. The Nuxt module and hosted Cloudflare and Vercel builds report this case as `DATABASE_NOT_FOUND` for `default`. Other runtimes report [`DATABASE_DISABLED`](https://vitehub.dev/docs/database/diagnostics/database_disabled).

An unknown name throws from `useDatabase(name)` before a query runs.

## Fix it

```diff [server/agents/support.ts]
 export default defineAgent({
   driver: { model },
   capabilities: [
-    db({ mode: 'read', database: 'analytic' }),
+    db({ mode: 'read', database: 'analytics' }),
   ],
 })
```

Use a discovered name. If the database does not exist yet, add a Definition, for example `src/analytics.database.ts` with `defineDatabase({ name: 'analytics', schema })`. A Named Database Definition must set `name` to the same name as its file.

For the Default Database case, select the Named Database that has the tables, as `useDatabase('analytics')`.

## Check the fix

Run `vitehub inspect definitions --kind database`. It lists the discovered databases with their names and files. The name in your code must be in that list. For the export command, run `vitehub database export --database <name>` with a listed name.

## Related

- [Define a database](https://vitehub.dev/docs/database/configure#define-a-database)
- [Use Named Databases](https://vitehub.dev/docs/database/server-api#use-named-databases)
- [Database Capability options](https://vitehub.dev/docs/database/agent-capability#options)
- [Export a Database](https://vitehub.dev/docs/development/cli#export-a-database)
- [`DATABASE_DISABLED`](https://vitehub.dev/docs/database/diagnostics/database_disabled)
- [`DATABASE_NAME_MISMATCH`](https://vitehub.dev/docs/database/diagnostics/database_name_mismatch)

## Source

`DATABASE_NOT_FOUND` belongs to the `database` package. Its catalog entry is in [`src/error-diagnostics.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/database/src/error-diagnostics.ts#L166). It is raised in [`src/cli.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/database/src/cli.ts#L173), [`src/cli.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/database/src/cli.ts#L218), [`src/cli.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/database/src/cli.ts#L360), [`src/runtime/agent.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/database/src/runtime/agent.ts#L21), [`src/runtime/agent.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/database/src/runtime/agent.ts#L25), and 6 more places.

See [all Database diagnostics](https://vitehub.dev/docs/database/diagnostics).

<!-- 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)

Next: [DATABASE_PGLITE_NOT_INSTALLED](https://vitehub.dev/raw/docs/database/diagnostics/database_pglite_not_installed.md)

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