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

Keep only 'path' inside docs and remove other keys

Unknown run config key 'docs.${unknownDocsKey}'.

Error message

Unknown run config key 'docs.${unknownDocsKey}'.

What it means

The 'docs' object currently accepts only the 'path' key; any other key inside docs is rejected so stale or misspelled options fail loudly.

Source

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

    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');
    if (unknownDocsKey) {
      throw new Error(`Unknown run config key 'docs.${unknownDocsKey}'.`);
    }
  }

  const candidate = {
    ...(value.assistant !== undefined || value.defaultAssistant !== undefined
      ? { assistant: value.assistant ?? value.defaultAssistant }
      : {}),
    ...(value.assistants !== undefined ? { assistants: value.assistants } : {}),
    ...(value.aliases !== undefined ? { aliases: value.aliases } : {}),
    ...(value.tiers !== undefined ? { tiers: value.tiers } : {}),
    ...(value.workflows !== undefined ? { workflows: value.workflows } : {}),
    ...(isRecord(docs) && docs.path !== undefined ? { docsPath: docs.path } : {}),
    ...(value.env !== undefined ? { envVars: value.env } : {}),
  };
  const parsed = workflowRunConfigLayerSchema.safeParse(candidate);
  if (!parsed.success) throw validationError(parsed.error);
  return { layer: normalizeRunConfigSemantics(parsed.data), source };
}

View on GitHub (pinned to 0773b97458)

Solutions

Keep only 'path' inside docs and remove other keys
Move any extra settings to a supported location in the config
Check current docs for the accepted docs schema

Example fix

// before
docs:
  root: ./docs
// after
docs:
  path: ./docs

Defensive patterns

Strategy: validation

Validate before calling

function assertDocsKeys(doc) { const extra = Object.keys(doc.docs ?? {}).filter(k => k !== 'path'); if (extra.length) throw new Error(`Unknown docs keys: ${extra.join(', ')}`); }

Type guard

function isDocsConfig(v) { return typeof v === 'object' && v !== null && Object.keys(v).every(k => k === 'path'); }

Try / catch

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

Prevention

Only use 'path' inside docs; look up current docs for accepted keys
Do not copy docs options from other tools
Schema-validate the docs object before loading

When it happens

Trigger: Passing docs: { url: ..., root: ... } or any key other than 'path' to parseWorkflowRunConfig().

Common situations: Guessing at docs option names; copying options from another tool's docs config; older examples using keys that no longer exist.

Related errors

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