coleam00/Archon · warning

${label}: unknown key '${key}' will be ignored.${hint}

Error message

${label}: unknown key '${key}' will be ignored.${hint}

What it means

The loader parses workflow YAML with Zod, which silently strips unrecognized keys. pushUnknownConfigKeyWarning detects stripped keys and pushes a warning naming the location (label), the ignored key, and an optional hint, so authors learn that a typo'd or misplaced field had no effect. The warning is also logged because the run path reads the log line, not the warnings array (#2213).

Source

Thrown at packages/workflows/src/loader.ts:274

 *
 * `id` is the bare node or workflow id — a stable value a log consumer can
 * filter on. `label` is its human rendering (it may carry a breadcrumb, e.g.
 * `Node 'refine' → loop_group node 'check'`) and appears only inside the
 * message prose, never as a structured field.
 */
function pushUnknownKeyWarning(
  id: string,
  label: string,
  key: string,
  hint: string,
  event: string,
  warnings: string[]
): void {
  const message = `${label}: unknown key '${key}' will be ignored.${hint}`;
  warnings.push(message);
  // Carry the prose, not just the payload: the run path (`archon workflow run`)
  // reads this log line and never reads the warning string (#2213).
  getLog().warn({ id, key, warning: message }, event);
}

/**
 * Warn about keys Zod silently stripped from a nested config object, recursing
 * through the sub-objects `spec` describes. `keyPath` is the dotted prefix that
 * locates the key inside the node (e.g. `approval.on_reject.`).
 */
function collectUnknownConfigKeys(
  raw: unknown,
  spec: NestedKeySpec,
  id: string,
  label: string,
  keyPath: string,
  event: string,
  warnings: string[]
): void {
  if (spec.kind === 'array') {
    if (!Array.isArray(raw)) return;

View on GitHub (pinned to 0773b97458)

Solutions

1. Fix or remove the unknown key named in the warning; check the workflow schema/docs for correct spelling and location.
2. Move the key to the correct nesting level if it belongs to a nested object — the label locates it (e.g. `approval.on_reject.` prefix).
3. Verify against the installed Archon version's docs; the key may not exist in your version or may come from a newer one.
4. Lint authored workflow YAML in CI so unknown keys block merge before a run silently misbehaves.

Example fix

# before
nodes:
  build:
    type: bash
    commad: echo hi   # typo — silently ignored
# after
nodes:
  build:
    type: bash
    command: echo hi

// Validate workflow YAML at author time and treat unknown-key warnings as failures:
const { warnings } = parseWorkflow(yamlSource);
const unknown = warnings.filter((w) => w.includes("unknown key"));
if (unknown.length > 0) {
  throw new Error('Workflow config has unknown keys:\n' + unknown.join('\n'));
}

When it happens

Trigger: parseWorkflow → collectUnknownConfigKeys / collectUnknownNodeKeys → pushUnknownConfigKeyWarning on any workflow containing a key absent from the Zod schema — a typo (e.g. `commad:` instead of `command:`), a valid field at the wrong nesting level, or a field from a newer/older Archon version than installed.

Common situations: Typoed YAML keys; copying a field between node types that don't support it; using fields documented for a newer release than the installed one; nesting a valid key one level too deep (hint often points to the right sub-object, e.g. `approval.on_reject.`).

Related errors

• Invalid run config at 'document': expected an object
• Invalid run config at 'docs': expected an object
• include target '${name}' not found
• Alias name '${name}' must start with '@' (e.g. '@${name}').
• Alias '${name}' has invalid provider — must be a non-empty s

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