coleam00/Archon · error · Error

Alias '${name}' has invalid provider — must be a non-empty s

Error message

Alias '${name}' has invalid provider — must be a non-empty string.

What it means

`assertValidEntry` enforces that each alias entry's `provider` field is a non-empty string. The library throws this during profile construction because an alias without a usable provider cannot be resolved to any SDK model binding.

Source

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

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.`);
  }
}

export type RunModelPresetValidationIssue =
  | { kind: 'unknown-provider'; provider: string; field: 'provider' }
  | { kind: 'invalid-model'; provider: string; model: string; reason: string; field: 'model' }
  | { kind: 'unsupported-effort'; provider: string; effort: string; field: 'effort' }
  | {
      kind: 'invalid-effort';

View on GitHub (pinned to 0773b97458)

Solutions

Set `provider` to a non-empty registered provider name (e.g. anthropic, openai)
Check YAML indentation so `provider:` is a direct child of the alias entry
Look for a misspelled key that left the real provider under a different field

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

// Shape-check alias entries before profile build.
function hasValidProvider(entry: unknown): entry is { provider: string; model: string } {
  return typeof entry === 'object' && entry !== null &&
    typeof (entry as any).provider === 'string' && (entry as any).provider.length > 0;
}

Type guard

function hasNonEmptyString<K extends string>(obj: unknown, key: K): obj is Record<K, string> {
  return typeof obj === 'object' && obj !== null &&
    typeof (obj as Record<string, unknown>)[key] === 'string' &&
    ((obj as Record<string, unknown>)[key] as string).length > 0;
}

Try / catch

try {
  const profile = buildAiProfile(rawConfig);
} catch (err) {
  if (err instanceof Error && err.message.includes('invalid provider')) {
    const alias = err.message.match(/Alias '([^']+)'/)?.[1];
    throw new Error(`Alias ${alias} in config needs a non-empty provider: value`, { cause: err });
  }
  throw err;
}

Prevention

Verify YAML indentation puts provider: directly under each alias key
Use an editor YAML schema for the aliases config to catch empty/missing fields
Never leave provider: with an empty value; delete the alias instead if unused
Run config loading as part of CI or startup smoke checks

When it happens

Trigger: Defining an alias in the aliases config where `provider` is missing, an empty string, or not a string (e.g. a number or nested object) — evaluated via `buildAiProfile`.

Common situations: YAML indentation mistakes that nest the provider value under the wrong key, leaving `provider:` empty, typos like `provder:`, or programmatically built config passing undefined.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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