What causes "Unknown run config key '${key}'." in coleam00/Archon?

Fix or remove the unknown key in the run config

Unknown run config key '${key}'.

Error message

Unknown run config key '${key}'.

What it means

parseWorkflowRunConfig() only accepts known run config keys, checked against keyClassifications. Any unrecognized top-level key is rejected so typos and stale keys fail loudly instead of being silently ignored.

Source

Thrown at packages/core/src/config/run-config.ts:181

    ...(layer.assistants === undefined ? {} : { assistants }),
    ...(layer.tiers === undefined ? {} : { tiers }),
    ...(layer.aliases === undefined ? {} : { aliases }),
  };
}

/** Parse one explicitly selected sparse run config. Unlike shared config loading, this is fail-fast. */
export function parseWorkflowRunConfig(
  value: unknown,
  source: WorkflowRunConfigSource
): WorkflowRunConfigInput {
  if (!isRecord(value)) {
    throw new Error("Invalid run config at 'document': expected an object");
  }

  for (const key of Object.keys(value)) {
    const classification = keyClassifications[key as ConfigKey] as KeyClassification | undefined;
    if (!classification) {
      throw new Error(`Unknown run config key '${key}'.`);
    }
    if (classification.kind === 'unavailable') {
      throw new Error(`Run config key '${key}' cannot apply: ${classification.reason}.`);
    }
  }

  if (value.assistant !== undefined && value.defaultAssistant !== undefined) {
    throw new Error(
      "Run config cannot set both 'assistant' and 'defaultAssistant'; use one spelling."
    );
  }

  const docs = value.docs;
  if (docs !== undefined) {
    if (!isRecord(docs)) {
      throw new Error("Invalid run config at 'docs': expected an object");
    }
    const unknownDocsKey = Object.keys(docs).find(key => key !== 'path');

View on GitHub (pinned to 0773b97458)

Solutions

Fix or remove the unknown key in the run config
Check the current run config key list in the docs for the exact spelling
If migrating from an older version, replace deprecated keys with their current names

Example fix

// before
asistant: claude
// after
assistant: claude

Defensive patterns

Strategy: validation

Validate before calling

const KNOWN_KEYS = new Set(['assistant','defaultAssistant','docs','assistants']); function assertKnownKeys(doc) { for (const k of Object.keys(doc)) if (!KNOWN_KEYS.has(k)) throw new Error(`Unknown run config key '${k}'`); }

Type guard

function hasOnlyKnownKeys(v, known) { return typeof v === 'object' && v !== null && Object.keys(v).every(k => known.has(k)); }

Try / catch

try { cfg = parseWorkflowRunConfig(doc, source); } catch (e) { const m = String(e.message).match(/Unknown run config key '(\S+)'/); if (m) console.error(`Remove or rename key: ${m[1]}`); throw e; }

Prevention

Keep a current list of valid run config keys handy or generate one from the schema
Run config files through schema validation (zod/JSON schema) before loading
Watch for renames between Archon versions when upgrading

When it happens

Trigger: Passing a run config document with a top-level key not in the ConfigKey set (typo like 'asistant', renamed key, leftover from an older version).

Common situations: Typo in a run config YAML file; following outdated docs or an example from an older release; copy-pasting keys from a different config surface.

Related errors

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