coleam00/Archon · error · Error

Model override '${targetName}' has invalid model '${spec}'.

Error message

Model override '${targetName}' has invalid model '${spec}'. Expected <agent>/<model> or <vendor>/<model>.

What it means

Thrown by resolveRunOverrideSpec when a spec is neither '<registered-provider>/<model>' nor a parseable Pi model ref. This is the fallback rejection for any override string the resolver cannot interpret.

Source

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

  }

  const prefix = spec.slice(0, slash);
  const remainder = spec.slice(slash + 1);
  if (isRegisteredProvider(prefix)) {
    if (remainder.length === 0) {
      throw new Error(`Model override '${targetName}' has an empty model id.`);
    }
    if (prefix === 'pi' && !parsePiModelRef(remainder)) {
      throw new Error(
        `Model override '${targetName}' has invalid Pi model '${remainder}'. ` +
          "Pi overrides need a vendor prefix, e.g. 'pi/minimax/minimax-m3'."
      );
    }
    return normalizeRunOverridePreset(targetName, { provider: prefix, model: remainder });
  }

  if (!parsePiModelRef(spec)) {
    throw new Error(
      `Model override '${targetName}' has invalid model '${spec}'. Expected <agent>/<model> or <vendor>/<model>.`
    );
  }
  return normalizeRunOverridePreset(targetName, { provider: 'pi', model: spec });
}

/**
 * Resolve one invocation's string mappings against the already-layered lower
 * profile. This is the only transport-to-profile boundary used by CLI and HTTP.
 */
export function resolveRunModelOverrides(
  profile: ResolvedAiProfile,
  overrides: RunModelOverrides | undefined
): ResolvedRunModelOverrides {
  if (!overrides) return {};

  const tiers: RawTiersConfig = {};
  for (const [name, spec] of Object.entries(overrides.tiers ?? {})) {

View on GitHub (pinned to 0773b97458)

Solutions

Write the override as <agent>/<model> or <vendor>/<model>, e.g. 'openai/gpt-4o' or 'pi/minimax/minimax-m3'.
Verify the prefix against the registered provider list (isRegisteredProvider).
If the model is only reachable via Pi, prefix it with 'pi/' and a vendor segment.
Run the spec through parsePiModelRef or resolveRunOverrideSpec in a quick script to confirm the accepted form.

Example fix

// before
--model large=gpt-4o
// after
--model large=openai/gpt-4o

Defensive patterns

Strategy: validation

Validate before calling

function looksLikeOverrideSpec(spec: string, registered: string[]): boolean {
  const slash = spec.indexOf('/');
  if (slash > 0 && registered.includes(spec.slice(0, slash))) {
    return spec.slice(slash + 1).length > 0;
  }
  return slash > 0; // plausible <agent>/<model> / <vendor>/<model>
}

Type guard

function isPrefixedModelSpec(spec: string): spec is `${string}/${string}` {
  return spec.includes('/') && !spec.startsWith('/') && !spec.endsWith('/');
}

Try / catch

try {
  resolveRunModelOverrides(assignments);
} catch (err) {
  if (err instanceof Error && err.message.includes('has invalid model')) {
    throw new Error(`Use <agent>/<model> or <vendor>/<model> form (${err.message})`);
  }
  throw err;
}

Prevention

Never pass a bare model id; always include an agent or vendor prefix.
Keep the registered-provider list handy (or import isRegisteredProvider) when generating specs.
Add a unit test that feeds each configured override through resolveRunOverrideSpec.
Centralize override construction in one helper instead of scattering string concatenation.

When it happens

Trigger: resolveRunModelOverrides with a spec whose prefix is not a registered provider AND whose whole string fails parsePiModelRef, e.g. 'gpt-4o' (no slash), 'myagent/', or 'foo/bar' with unknown provider 'foo'.

Common situations: Passing a bare model name instead of the required <agent>/<model> or <vendor>/<model> form; typos in the provider/agent name; older configs written for a version that accepted bare model ids.

Related errors

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