coleam00/Archon · error · InvalidProviderRunConfigError

unknown provider setting

Error message

unknown provider setting

What it means

assertKnownRunConfigKeys rejects provider run-config objects containing any key outside the provider's allowed set. Each provider parser (Claude, Codex, Copilot, Opencode, Pi) declares the settings it understands; anything else throws InvalidProviderRunConfigError naming the offending key, because unknown settings would otherwise be silently ignored and mask config mistakes.

Source

Thrown at packages/providers/src/shared/run-config.ts:9

import { InvalidProviderRunConfigError } from '../errors';

export function assertKnownRunConfigKeys(
  raw: Record<string, unknown>,
  allowed: readonly string[]
): void {
  const unknown = Object.keys(raw).find(key => !allowed.includes(key));
  if (unknown !== undefined) {
    throw new InvalidProviderRunConfigError(unknown, 'unknown provider setting');
  }
}

export function invalidRunConfigValue(fieldPath: string, expected: string): never {
  throw new InvalidProviderRunConfigError(fieldPath, `expected ${expected}`);
}

export function normalizeRunConfigString(value: unknown, fieldPath: string): string | undefined {
  if (value === undefined) return undefined;
  if (typeof value !== 'string' || value.trim().length === 0) {
    invalidRunConfigValue(fieldPath, 'a non-blank string');
  }
  return value.trim();
}

export function isConfigRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}

View on GitHub (pinned to 0773b97458)

Solutions

1. Remove the offending key (named in the error) from the run config
2. Check the target provider's allowed keys and use the correct option name
3. Move provider-specific settings to the config of the provider that supports them
4. Update renamed options after an Archon upgrade

Example fix

// before
parseClaudeRunConfig({ model: 'claude-sonnet-4', temperature: 0.5 });
// after (temperature not supported by Claude run config)
parseClaudeRunConfig({ model: 'claude-sonnet-4' });

const allowedClaudeKeys = ['model']; // see the provider parser's allowed list
const unknown = Object.keys(rawRunConfig).filter(k => !allowedClaudeKeys.includes(k));
if (unknown.length) console.error(`Unknown settings for provider: ${unknown.join(', ')}`);

function hasOnlyKeys<T extends object>(raw: object, allowed: readonly (keyof T)[]):
  raw is Pick<T, keyof T & string> {
  return Object.keys(raw).every(k => (allowed as readonly string[]).includes(k));
}

import { InvalidProviderRunConfigError } from '@archon/providers';
try {
  cfg = parseClaudeRunConfig(raw);
} catch (err) {
  if (err instanceof InvalidProviderRunConfigError) {
    console.error(`Remove or rename setting '${err.fieldPath}' for this provider`);
  }
  throw err;
}

When it happens

Trigger: Passing a run config with a key not in the provider's allowed list — e.g. 'temperature' to a provider that doesn't support it, a typo like 'modle', or an option renamed between versions.

Common situations: Sharing one run-config object across different providers; typos in YAML/JSON run settings; upgrading Archon and using removed/renamed provider options; copying config examples for a different provider.

Related errors

• expected ${expected}
• No chat in context
• Gitea API error: ${String(response.status)} ${response.statu
• Gitea API error: ${String(response.status)}
• Invalid container.network '${network}' in .archon/config.yam

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