mastra-ai/mastra · error · Error

The --empty and --template options can't be used together

Error message

The --empty and --template options can't be used together

What it means

`validateCreateOptionConflicts` in packages/cli/src/commands/create/command.ts:107 rejects mutually exclusive `mastra create` flags. `--empty` scaffolds a bare project while `--template` scaffolds from a template; the CLI cannot do both, so it throws before any file system work. This is a fast-fail input validation guard so users get an immediate, actionable message.

Source

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

    llmProvider: options.llm,
    llmApiKey: options.llmApiKey,
    skills: options.skills,
    git: options.git,
    template: options.template,
    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();

View on GitHub (pinned to 75dd419e61)

Solutions

1. Remove either the `--empty` flag or the `--template` flag — pick one mode
2. If you want a template, drop `--empty`: `mastra create my-app --template <slug>`
3. If you want an empty scaffold, drop `--template`: `mastra create my-app --empty`

Example fix

// before
mastra create my-app --empty --template template-agent-harness
// after
mastra create my-app --template template-agent-harness

const empty = process.argv.includes('--empty');
const hasTemplate = process.argv.includes('-t') || process.argv.includes('--template');
if (empty && hasTemplate) {
  throw new Error('Remove either --empty or --template before running mastra create');
}

When it happens

Trigger: Running e.g. `mastra create my-app --empty --template <slug>` or passing both `{ empty: true, template: 'x' }` to the programmatic `create()` API (both are normalized into NormalizedCreateOptions and checked together).

Common situations: Scripting the CLI and appending both flags from separate config values; combining a saved alias like `mastra create --empty -t my-template`; migrating shell scripts where a template flag was added to an existing empty-project command.

Related errors

• The --llm option can only be used with the default template
• The --llm-api-key option can only be used with the default t
• MALFORMED_HEADER
• MISSING_INPUT
• INVALID_JSON

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