What causes "Invalid run config at 'docs': expected an object" in coleam00/Archon?

Wrap the value as an object: docs: { path: }

Invalid run config at 'docs': expected an object

Error message

Invalid run config at 'docs': expected an object

What it means

If present, the 'docs' run config key must be an object (currently holding only 'path'). A non-object docs value is rejected fail-fast by parseWorkflowRunConfig().

Source

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

    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');
    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 } : {}),
  };

View on GitHub (pinned to 0773b97458)

Solutions

Wrap the value as an object: docs: { path: <path> }
Quote paths so YAML does not collapse them
Remove docs entirely if not needed

Example fix

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

Defensive patterns

Strategy: type-guard

Validate before calling

function assertDocsShape(doc) { if (doc.docs !== undefined && (typeof doc.docs !== 'object' || doc.docs === null || Array.isArray(doc.docs))) throw new Error('docs must be an object with a path key'); }

Type guard

function isValidDocs(v) { return v === undefined || (typeof v === 'object' && v !== null && !Array.isArray(v)); }

Try / catch

try { cfg = parseWorkflowRunConfig(doc, source); } catch (e) { if (String(e.message).includes("at 'docs'")) console.error('Use docs: { path: ... }'); throw e; }

Prevention

Always write docs as a mapping: docs: { path: ... }
Quote path values in YAML so they stay strings
Validate docs shape in a pre-load schema check

When it happens

Trigger: Passing docs as a string, array, number, or null, e.g. docs: ./docs instead of docs: { path: ./docs }.

Common situations: Shorthand assumptions where a string path is written directly; YAML merging that flattens docs to a scalar.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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