coleam00/Archon · error · Error

Model binding '${name}' has an invalid effort.

Error message

Model binding '${name}' has an invalid effort.

What it means

`assertValidPersistedPreset` validates persisted model bindings when they are read back from metadata (`readRunModelBindingsMetadata`). If a binding carries an `effort` that the provider does not accept (checked via `isEffortValidForProvider`), the library throws rather than silently dropping the effort — persisted state may be stale relative to the provider registry.

Source

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

  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';
      provider: string;
      effort: string;
      valid: readonly string[];
      field: 'effort';
    }
  | { kind: 'unsupported-thinking'; provider: string; field: 'thinking' };

function runModelPresetValidationMessage(issue: RunModelPresetValidationIssue): string {
  switch (issue.kind) {

View on GitHub (pinned to 0773b97458)

Solutions

1. Remove the `effort` field from the offending binding so it resolves with provider defaults
2. Replace the effort value with one valid for that provider (check validEffortsForProvider / provider docs)
3. Re-save the binding through the normal run-override flow instead of editing metadata by hand

Example fix

// before (persisted metadata)
{ "name": "@fast", "provider": "openai", "model": "gpt-4o-mini", "effort": "maximal" }
// after
{ "name": "@fast", "provider": "openai", "model": "gpt-4o-mini" }

import { isEffortValidForProvider } from '@archon/workflows/model-validation';
// Validate persisted bindings before reading them into a run.
function badBindings(bindings: { name: string; provider: string; effort?: string }[]): string[] {
  return bindings
    .filter((b) => b.effort !== undefined && !isEffortValidForProvider(b.provider, b.effort))
    .map((b) => b.name);
}

try {
  const bindings = readRunModelBindingsMetadata(metadata);
} catch (err) {
  if (err instanceof Error && err.message.includes('has an invalid effort')) {
    const name = err.message.match(/'([^']+)'/)?.[1];
    throw new Error(`Binding '${name}' has a stale effort for its provider; re-save it via the run override flow`, { cause: err });
  }
  throw err;
}

When it happens

Trigger: Reading run model bindings from workflow metadata where a binding's `effort` value is not valid for its `provider` — e.g. effort persisted by an older binary or hand-edited metadata, or a provider whose supported effort set changed.

Common situations: Hand-editing workflow metadata `model_bindings`, upgrading Archon after a provider's valid effort levels changed, copying an effort value from one provider to another that doesn't support it.

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

• unknown-provider: provider '${preset.provider}' is not a reg
• Invalid run config at 'document': expected an object
• Unknown run config key '${key}'.
• Run config key '${key}' cannot apply: ${classification.reaso
• Run config cannot set both 'assistant' and 'defaultAssistant

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