mastra-ai/mastra · error · Error

Database not found: ${dbArg}. List databases with: mastra en

Error message

Database not found: ${dbArg}. List databases with: mastra env db list

What it means

findDatabase() fetches all databases for the resolved project and matches the dbArg by id or name; if nothing matches it throws with a hint to run `mastra env db list`. This guards all db subcommands (show/delete/etc.) against referencing a database that does not exist in that project.

Source

Thrown at packages/cli/src/commands/db/db.ts:201

function envVarNamesFor(kind: DatabaseKind): string {
  const names = DB_ENV_VAR_NAMES[kind] ?? [];
  return names.length > 0 ? names.join(', ') : '—';
}

function withScope(db: ProjectDatabase, environments: Environment[]) {
  return {
    ...db,
    scope: formatScope(db, environments),
    envVarNames: DB_ENV_VAR_NAMES[db.kind] ?? [],
  };
}

async function findDatabase(token: string, orgId: string, project: Project, dbArg: string): Promise<ProjectDatabase> {
  const databases = await fetchDatabases(token, orgId, project.id);
  const db = databases.find(d => d.id === dbArg || d.name === dbArg);
  if (!db) {
    throw new Error(`Database not found: ${dbArg}. List databases with: mastra env db list`);
  }
  return db;
}

/* ------------------------------------------------------------------ */
/*  mastra env db list                                                 */
/* ------------------------------------------------------------------ */

async function findEnvironment(token: string, orgId: string, project: Project, envArg: string): Promise<Environment> {
  const environments = await fetchEnvironments(token, orgId, project.id);
  const env = environments.find(e => e.id === envArg || e.name === envArg || e.slug === envArg);
  if (!env) {
    throw new Error(`Environment not found: ${envArg}. List environments with: mastra env list`);
  }
  return env;
}

async function listDatabasesAction(envArg: string | undefined, options: { project?: string; json?: boolean }) {

View on GitHub (pinned to 75dd419e61)

Solutions

Run `mastra env db list` and copy the exact id or name of the target database.
Confirm the correct project with `--project <name>` if the database lives in a different project.
Re-check spelling/case of the database name; names are matched exactly.
If the database was deleted, recreate it with `mastra env db create`.

Example fix

// before
mastra env db delete my-db
// after
mastra env db list
mastra env db delete prod-main-db

Defensive patterns

Strategy: validation

Validate before calling

const dbs = await listDatabases(); // or parse `mastra env db list --json`
if (!dbs.some(d => d.id === dbArg || d.name === dbArg)) {
  throw new Error(`Unknown database "${dbArg}" — pick one of: ${dbs.map(d => d.name).join(', ')}`);
}

Try / catch

try {
  await runDbCommand(dbArg);
} catch (e) {
  if (/Database not found/.test((e as Error).message)) {
    console.error('Run `mastra env db list` and use an exact id/name; check --project scope.');
  }
}

Prevention

Always resolve names via `mastra env db list` (or --json) instead of hardcoding.
Pass --project explicitly when the database isn't in the default project.
Prefer stable database ids over mutable names in scripts.

When it happens

Trigger: `mastra env db <cmd> <dbArg>` where dbArg is neither an existing database id nor name within the current org/project — wrong project scope, deleted database, or typo.

Common situations: Passing a database from another project (project not selected with --project), using a stale name after a rename, or confusing environments' scoped vs shared databases.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/7194f92f81c64e89. Report an issue: GitHub.