mastra-ai/mastra · error · Error

Cannot combine an environment argument with --shared. Pick o

Error message

Cannot combine an environment argument with --shared. Pick one scope.

What it means

createDatabaseAction rejects mutually exclusive scoping inputs: a positional environment argument (environment-scoped database) and the --shared flag (project-scoped database). Exactly one scope must be chosen, so the CLI fails fast instead of guessing.

Source

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

  return kind;
}

async function createDatabaseAction(
  envArg: string | undefined,
  options: {
    project?: string;
    kind: string;
    name?: string;
    region?: string;
    shared?: boolean;
    wait: boolean;
    json?: boolean;
  },
) {
  const kind = parseKind(options.kind);

  if (envArg && options.shared) {
    throw new Error('Cannot combine an environment argument with --shared. Pick one scope.');
  }

  const token = await getToken();
  const { orgId } = await resolveCurrentOrg(token);
  const project = await resolveProject(token, orgId, options.project);

  const environment = options.shared
    ? undefined
    : envArg
      ? await findEnvironment(token, orgId, project, envArg)
      : await resolveDefaultEnvironment(token, orgId, project, { json: options.json });

  if (environment && options.region && !options.json) {
    console.info(`Note: --region is ignored for environment-scoped databases; the environment's region is used.`);
  }

  await createDatabase({
    token,

View on GitHub (pinned to 75dd419e61)

Solutions

Drop the environment argument to create a project-scoped shared database: `mastra env db create --shared --kind turso`.
Or drop --shared to create an environment-scoped database: `mastra env db create <env> --kind turso`.
In scripts, make the scope conditional so only one of the two is ever passed.

Example fix

// before
mastra env db create production --shared --kind turso
// after
mastra env db create --shared --kind turso  # or: mastra env db create production --kind turso

Defensive patterns

Strategy: validation

Validate before calling

if (envArg && shared) {
  throw new Error('Pass either an environment argument or --shared, not both.');
}

Try / catch

try {
  await createDatabase(envArg, { shared, kind });
} catch (e) {
  if (/Cannot combine an environment argument with --shared/.test((e as Error).message)) {
    console.error('Choose one scope: drop the env arg (shared) or drop --shared (env-scoped).');
  }
}

Prevention

Model scope in scripts as a single enum ('env' | 'shared') so both can't be set.
Review CLI wrappers that merge user args with config defaults — --shared defaults to false, don't force it.
Remember --shared replaces the environment argument; it does not modify it.

When it happens

Trigger: `mastra env db create <env> --shared --kind ...` — an environment positional is present while --shared is set.

Common situations: Scripting the command with both a default env arg and a --shared flag enabled in config, or misunderstanding that --shared replaces (not augments) the environment argument.

Related errors

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