coleam00/Archon · error · Error

Unknown alias '${ref}'. Defined aliases: ${list}

Error message

Unknown alias '${ref}'. Defined aliases: ${list}

What it means

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.

Source

Thrown at packages/workflows/src/model-validation.ts:592

}

/**
 * Classify a `model:` reference and resolve it against the profile.
 *   - tier ('small' | 'medium' | 'large') → preset via fallback chain
 *   - '@<name>' → preset from profile.aliases, or throw if unknown
 *   - anything else → { literal: ref } pass-through
 */
export function resolveModelSpec(profile: ResolvedAiProfile, ref: string): ResolvedModelSpec {
  if (isTierName(ref)) {
    return resolveTierWithFallback(profile, ref).preset;
  }

  if (ref.startsWith('@')) {
    const preset = profile.aliases[ref];
    if (preset) return preset;
    const defined = Object.keys(profile.aliases);
    const list = defined.length > 0 ? defined.join(', ') : '(none)';
    throw new Error(`Unknown alias '${ref}'. Defined aliases: ${list}`);
  }

  return { literal: ref };
}

/** Type guard — narrows ResolvedModelSpec to its `{ literal }` variant. */
export function isLiteralSpec(spec: ResolvedModelSpec): spec is { literal: string } {
  return 'literal' in spec;
}

/**
 * The reasoning-depth vocabulary a provider accepts, or `null` when it has no
 * reasoning control at all (OpenCode configures reasoning in `opencode.json`,
 * not per request).
 *
 * There is one vocabulary now, not one per provider (#2556): every provider
 * with `effortControl` takes the whole ladder and clamps any rung its SDK lacks
 * to the nearest one it has. So this answers "does effort reach this provider",

View on GitHub (pinned to 0773b97458)

Solutions

  1. Define the alias: `archon ai alias set <name> <provider> <model>` (or the console AI Settings panel).
  2. Or correct the `@ref` spelling to match a listed defined alias.
  3. Or replace the reference with a literal model id string.

Example fix

// before
model: '@sonnet'
// after (alias defined first)
// archon ai alias set sonnet anthropic claude-sonnet-4
model: '@sonnet'
Defensive patterns

Strategy: validation

Validate before calling

function assertAliasDefined(profile: ProviderProfile, ref: string): void {
  if (ref.startsWith('@') && !(ref in profile.aliases)) {
    throw new Error(`Alias ${ref} missing. Defined: ${Object.keys(profile.aliases).join(', ') || '(none)'}`);
  }
}

Type guard

function isKnownAlias(profile: ProviderProfile, ref: string): boolean {
  return !ref.startsWith('@') || ref in profile.aliases;
}

Try / catch

try {
  const spec = resolveModelSpec(profile, nodeModelRef);
} catch (err) {
  if ((err as Error).message.startsWith('Unknown alias')) {
    const alias = nodeModelRef;
    console.error(`${alias} not defined; create it with 'archon ai alias set ${alias.slice(1)} <provider> <model>'`);
  } else throw err;
}

Prevention

When it happens

Trigger: 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`.

Common situations: 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.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/2755ed83d4c3fb54. Report an issue: GitHub.