{"record":{"id":"2755ed83d4c3fb54","repo":"coleam00/Archon","slug":"unknown-alias-ref-defined-aliases-list","errorCode":null,"errorMessage":"Unknown alias '${ref}'. Defined aliases: ${list}","messagePattern":"Unknown alias '(.+?)'\\. Defined aliases: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/workflows/src/model-validation.ts","lineNumber":592,"sourceCode":"}\n\n/**\n * Classify a `model:` reference and resolve it against the profile.\n *   - tier ('small' | 'medium' | 'large') → preset via fallback chain\n *   - '@<name>' → preset from profile.aliases, or throw if unknown\n *   - anything else → { literal: ref } pass-through\n */\nexport function resolveModelSpec(profile: ResolvedAiProfile, ref: string): ResolvedModelSpec {\n  if (isTierName(ref)) {\n    return resolveTierWithFallback(profile, ref).preset;\n  }\n\n  if (ref.startsWith('@')) {\n    const preset = profile.aliases[ref];\n    if (preset) return preset;\n    const defined = Object.keys(profile.aliases);\n    const list = defined.length > 0 ? defined.join(', ') : '(none)';\n    throw new Error(`Unknown alias '${ref}'. Defined aliases: ${list}`);\n  }\n\n  return { literal: ref };\n}\n\n/** Type guard — narrows ResolvedModelSpec to its `{ literal }` variant. */\nexport function isLiteralSpec(spec: ResolvedModelSpec): spec is { literal: string } {\n  return 'literal' in spec;\n}\n\n/**\n * The reasoning-depth vocabulary a provider accepts, or `null` when it has no\n * reasoning control at all (OpenCode configures reasoning in `opencode.json`,\n * not per request).\n *\n * There is one vocabulary now, not one per provider (#2556): every provider\n * with `effortControl` takes the whole ladder and clamps any rung its SDK lacks\n * to the nearest one it has. So this answers \"does effort reach this provider\",","sourceCodeStart":574,"sourceCodeEnd":610,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/workflows/src/model-validation.ts#L574-L610","documentation":"resolveModelSpec resolves a `@name` model reference through the provider profile's alias map. When the alias is not defined, the error lists every alias that IS defined (or '(none)') so the author can correct the reference to a literal model id or a defined alias.","triggerScenarios":"A workflow node or config references a model as `@my-alias` but `profile.aliases` contains no `@my-alias` key — typo, alias defined only in another user's profile, or alias never created with `archon ai alias set`.","commonSituations":"Copy-pasting a workflow that used aliases from another install; renaming an alias without updating workflows; per-user profiles where the alias exists for one user but not the one running the workflow.","solutions":["Define the alias: `archon ai alias set <name> <provider> <model>` (or the console AI Settings panel).","Or correct the `@ref` spelling to match a listed defined alias.","Or replace the reference with a literal model id string."],"exampleFix":"// before\nmodel: '@sonnet'\n// after (alias defined first)\n// archon ai alias set sonnet anthropic claude-sonnet-4\nmodel: '@sonnet'","handlingStrategy":"validation","validationCode":"function assertAliasDefined(profile: ProviderProfile, ref: string): void {\n  if (ref.startsWith('@') && !(ref in profile.aliases)) {\n    throw new Error(`Alias ${ref} missing. Defined: ${Object.keys(profile.aliases).join(', ') || '(none)'}`);\n  }\n}","typeGuard":"function isKnownAlias(profile: ProviderProfile, ref: string): boolean {\n  return !ref.startsWith('@') || ref in profile.aliases;\n}","tryCatchPattern":"try {\n  const spec = resolveModelSpec(profile, nodeModelRef);\n} catch (err) {\n  if ((err as Error).message.startsWith('Unknown alias')) {\n    const alias = nodeModelRef;\n    console.error(`${alias} not defined; create it with 'archon ai alias set ${alias.slice(1)} <provider> <model>'`);\n  } else throw err;\n}","preventionTips":["Run `archon ai alias list` after switching profiles or installs before running workflows.","Prefer literal model ids in shared/reference workflows; keep aliases in per-user config.","Grep the repo for '@' model refs and reconcile them with defined aliases in CI.","Define aliases per user profile you actually run under, not just the admin profile."],"tags":["configuration","model-alias","workflow"],"backgroundTag":"unknown-model-alias","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}