mastra-ai/mastra · error · Error

The --llm-api-key option can only be used with the default t

Error message

The --llm-api-key option can only be used with the default template

What it means

`validateCreateOptionConflicts` in packages/cli/src/commands/create/command.ts:115 throws when `--llm-api-key <key>` is passed with `--empty` or `--template`. The API key is only consumed by the managed default-template flow (it gets written into the adapted scaffold), so supplying it in other modes is a no-op the CLI rejects instead of silently ignoring.

Source

Thrown at packages/cli/src/commands/create/command.ts:115

}

export function getCreateMode(options: Pick<NormalizedCreateOptions, 'empty' | 'template'>): CreateMode {
  if (options.empty) return 'empty';
  if (options.template !== undefined) return 'template';
  return 'managed';
}

export function validateCreateOptionConflicts(options: NormalizedCreateOptions): CreateMode {
  if (options.empty && options.template !== undefined) {
    throw new Error(`The --empty and --template options can't be used together`);
  }

  const mode = getCreateMode(options);
  if (mode !== 'managed' && options.llmProvider !== undefined) {
    throw new Error('The --llm option can only be used with the default template');
  }
  if (mode !== 'managed' && options.llmApiKey !== undefined) {
    throw new Error('The --llm-api-key option can only be used with the default template');
  }

  return mode;
}

const WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
const PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;

export function validateProjectName(value: string): string {
  const projectName = value.trim();

  if (
    projectName.length < 1 ||
    projectName.length > 214 ||
    path.isAbsolute(projectName) ||
    projectName.includes('/') ||
    projectName.includes('\\') ||
    projectName === '.' ||

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Remove `-k/--llm-api-key` when using `--empty` or `--template`
  2. Use the default flow if you want the key wired in: `mastra create my-app --llm openai --llm-api-key sk-...`
  3. Prefer environment variables (e.g. OPENAI_API_KEY) in the generated project instead of passing keys via flags

Example fix

// before
mastra create my-app --empty --llm-api-key sk-abc123
// after
mastra create my-app --empty
Defensive patterns

Strategy: validation

Validate before calling

if ((opts.empty || opts.template !== undefined) && process.argv.some(a => a === '-k' || a === '--llm-api-key')) {
  throw new Error('--llm-api-key only applies to the default template flow');
}

Try / catch

try {
  await create(opts);
} catch (error) {
  if (error instanceof Error && error.message.includes('--llm-api-key')) {
    console.error('Remove -k/--llm-api-key or use the default flow');
  } else throw error;
}

Prevention

When it happens

Trigger: `mastra create --empty -k sk-...` or `mastra create -t <slug> -k sk-...` (or programmatic `{ empty/template, llmApiKey }`): mode !== 'managed' while llmApiKey is defined.

Common situations: Scripts that export an API key and always append `-k $MASTRA_KEY`; combining template scaffolding with credentials meant for the default flow; users hardcoding keys into CI commands for all create variants.

Related errors

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