coleam00/Archon · error · Error

Alias name '${name}' must start with '@' (e.g. '@${name}').

Error message

Alias name '${name}' must start with '@' (e.g. '@${name}'). Reserved tier names (small/medium/large) do not need '@'.

What it means

Custom alias names must be prefixed with `@` so the resolver can distinguish them from bare model literals and tier keywords. `assertCustomAliasPrefix` throws when an alias key lacks the `@` prefix; the error message echoes the name with the suggested corrected form.

Source

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

  Record<TierName, { model: string; effort?: string }>
>;

/** True when `value` is one of the reserved tier keywords (small/medium/large). */
export function isTierName(value: string): value is TierName {
  return (TIER_NAMES as readonly string[]).includes(value);
}

function assertNotReserved(name: string): void {
  if (isTierName(name)) {
    throw new Error(
      `Alias name '${name}' is reserved (small/medium/large are tier keywords). Use a different name.`
    );
  }
}

function assertCustomAliasPrefix(name: string): void {
  if (!name.startsWith('@')) {
    throw new Error(
      `Alias name '${name}' must start with '@' (e.g. '@${name}'). Reserved tier names (small/medium/large) do not need '@'.`
    );
  }
}

function assertValidEntry(name: string, entry: RawAliasEntry): void {
  if (typeof entry.provider !== 'string' || entry.provider.length === 0) {
    throw new Error(`Alias '${name}' has invalid provider — must be a non-empty string.`);
  }
  if (typeof entry.model !== 'string' || entry.model.length === 0) {
    throw new Error(`Alias '${name}' has invalid model — must be a non-empty string.`);
  }
}

function assertValidPersistedPreset(name: string, entry: ModelAliasPreset): void {
  if (entry.effort !== undefined && !isEffortValidForProvider(entry.provider, entry.effort)) {
    throw new Error(`Model binding '${name}' has an invalid effort.`);
  }

View on GitHub (pinned to 0773b97458)

Solutions

  1. Add the `@` prefix to the alias key, quoting it in YAML: `'@name':`
  2. Check the surrounding YAML didn't strip or mangle the `@` (quote the key if your YAML tool complains)
  3. Remember the alias is later referenced as `@name` in workflow `model:` fields

Example fix

# before
aliases:
  fast:
    provider: openai
    model: gpt-4o-mini
# after
aliases:
  '@fast':
    provider: openai
    model: gpt-4o-mini
Defensive patterns

Strategy: validation

Validate before calling

// Ensure every custom alias key is @-prefixed before config load.
function assertAliasPrefixes(aliases: Record<string, unknown>): void {
  for (const key of Object.keys(aliases)) {
    if (!['small', 'medium', 'large'].includes(key) && !key.startsWith('@')) {
      throw new Error(`Alias '${key}' must start with '@'`);
    }
  }
}

Type guard

function hasAliasPrefix(key: string): key is `@${string}` {
  return key.startsWith('@');
}

Try / catch

try {
  const profile = buildAiProfile(rawConfig);
} catch (err) {
  if (err instanceof Error && err.message.includes("must start with '@'")) {
    const name = err.message.match(/Alias name '([^']+)'/)?.[1] ?? '?';
    throw new Error(`Config error: rename alias '${name}' to '@${name}'`, { cause: err });
  }
  throw err;
}

Prevention

When it happens

Trigger: Declaring an alias entry whose key does not start with `@` in the aliases config, a run-model assignment, or an override preset — any path through `buildAiProfile`, `presetForOverrideTarget`, or `parseRunModelAssignments`. Tier keywords (small/medium/large) are the only unprefixed names allowed, and those are rejected earlier by assertNotReserved in the aliases context.

Common situations: Copy-pasting config examples that omit the `@`, writing `myalias:` instead of `'@myalias':`, YAML quoting confusion around the `@` character (some tools need the key quoted).

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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