mastra-ai/mastra · error · Error

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

Error message

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

What it means

`validateCreateOptionConflicts` in packages/cli/src/commands/create/command.ts:112 throws when `--llm <provider>` is combined with a non-default mode (`--empty` or `--template`). LLM provider preselection (which wires a default provider into the scaffold) only applies to the managed/default template flow; template and empty scaffolds bypass provider adaptation entirely.

Source

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

    timeout: options.timeout,
    install: options.install,
  };
}

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

View on GitHub (pinned to 75dd419e61)

Solutions

Drop `--llm` when using `--empty` or `--template`
Use the default flow if you need provider preselection: `mastra create my-app --llm openai`
If using `--template`, configure the provider manually inside the generated project afterwards

Example fix

// before
mastra create my-app --template template-agent-harness --llm openai
// after
mastra create my-app --template template-agent-harness

Defensive patterns

Strategy: validation

Validate before calling

function assertLlmFlagsAllowed(opts: { empty?: boolean; template?: string | boolean; llm?: string }) {
  const mode = opts.empty ? 'empty' : opts.template !== undefined ? 'template' : 'managed';
  if (mode !== 'managed' && opts.llm !== undefined) {
    throw new Error(`--llm cannot be combined with --${mode === 'empty' ? 'empty' : 'template'}`);
  }
}

Try / catch

try {
  await create({ ...opts });
} catch (error) {
  if (error instanceof Error && error.message.includes('--llm')) {
    console.error('Drop --llm or switch to the default template flow');
  } else throw error;
}

Prevention

Treat --llm as default-flow-only in scripts and docs
Build CLI invocations from a mode variable instead of concatenating all flags
Validate flag sets in CI when generating mastra create commands

When it happens

Trigger: `mastra create --empty --llm openai` or `mastra create -t <slug> --llm anthropic` (or programmatic `{ empty/template, llmProvider }`): getCreateMode returns 'empty'/'template' while llmProvider is set.

Common situations: Users chaining convenience flags assuming `--llm` works everywhere; CI scripts that always pass `--llm` and later added `--template`; confusion after reading docs that describe `--llm` only in the default-flow context.

Related errors

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