{"record":{"id":"c4b74f127f034954","repo":"mastra-ai/mastra","slug":"the-llm-option-can-only-be-used-with-the-default","errorCode":null,"errorMessage":"The --llm option can only be used with the default template","messagePattern":"The --llm option can only be used with the default template","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/create/command.ts","lineNumber":112,"sourceCode":"    timeout: options.timeout,\n    install: options.install,\n  };\n}\n\nexport function getCreateMode(options: Pick<NormalizedCreateOptions, 'empty' | 'template'>): CreateMode {\n  if (options.empty) return 'empty';\n  if (options.template !== undefined) return 'template';\n  return 'managed';\n}\n\nexport function validateCreateOptionConflicts(options: NormalizedCreateOptions): CreateMode {\n  if (options.empty && options.template !== undefined) {\n    throw new Error(`The --empty and --template options can't be used together`);\n  }\n\n  const mode = getCreateMode(options);\n  if (mode !== 'managed' && options.llmProvider !== undefined) {\n    throw new Error('The --llm option can only be used with the default template');\n  }\n  if (mode !== 'managed' && options.llmApiKey !== undefined) {\n    throw new Error('The --llm-api-key option can only be used with the default template');\n  }\n\n  return mode;\n}\n\nconst WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\\..*)?$/i;\nconst PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;\n\nexport function validateProjectName(value: string): string {\n  const projectName = value.trim();\n\n  if (\n    projectName.length < 1 ||\n    projectName.length > 214 ||\n    path.isAbsolute(projectName) ||","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/create/command.ts#L94-L130","documentation":"`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.","triggerScenarios":"`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.","commonSituations":"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.","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"],"exampleFix":"// before\nmastra create my-app --template template-agent-harness --llm openai\n// after\nmastra create my-app --template template-agent-harness","handlingStrategy":"validation","validationCode":"function assertLlmFlagsAllowed(opts: { empty?: boolean; template?: string | boolean; llm?: string }) {\n  const mode = opts.empty ? 'empty' : opts.template !== undefined ? 'template' : 'managed';\n  if (mode !== 'managed' && opts.llm !== undefined) {\n    throw new Error(`--llm cannot be combined with --${mode === 'empty' ? 'empty' : 'template'}`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await create({ ...opts });\n} catch (error) {\n  if (error instanceof Error && error.message.includes('--llm')) {\n    console.error('Drop --llm or switch to the default template flow');\n  } else throw error;\n}","preventionTips":["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"],"tags":["cli","input-validation","flag-conflict","llm-provider"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}