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

Wrap the config in a top-level mapping (key: value pairs)

Invalid run config at 'document': expected an object

Error message

Invalid run config at 'document': expected an object

What it means

parseWorkflowRunConfig() expects the top-level run config document to be an object (record). Any other type — string, array, number, null — is rejected with this fail-fast error before any keys are inspected.

Source

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

      alias,
      normalizePreset(`aliases.${alias}`, preset),
    ])
  );
  return {
    ...layer,
    ...(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."
    );
  }

View on GitHub (pinned to 0773b97458)

Solutions

Wrap the config in a top-level mapping (key: value pairs)
Check what the YAML file actually parses to; quote values that might collapse to scalars
Ensure callers pass a parsed object, not raw text

Example fix

// before (config.yaml)
just a string
// after
assistant: claude
docs:
  path: ./docs

Defensive patterns

Strategy: type-guard

Validate before calling

function assertRunConfigDocument(value) { if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('Run config must be a top-level object'); }

Type guard

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

Try / catch

try { cfg = parseWorkflowRunConfig(doc, source); } catch (e) { if (String(e.message).includes("at 'document'")) console.error('Run config file must contain a YAML mapping, not a scalar/list'); throw e; }

Prevention

Start run config YAML files with a mapping key, never a bare scalar
Check parsed YAML shape before handing it to the loader
Avoid empty run config files (they parse to null)

When it happens

Trigger: Passing a non-object (e.g. a YAML file that parses to a bare string or list, null, or an array) into parseWorkflowRunConfig(), e.g. via input() or loadWorkflowRunConfigFile().

Common situations: A run config YAML file containing only a scalar or a list; passing a JSON string instead of a parsed object; an empty file that parses to null.

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/d7719b727cd0eae5. Report an issue: GitHub.