Warning: '${workflowName}' declares keys the engine ignores:

Error message

Warning: '${workflowName}' declares keys the engine ignores:

What it means

Header warning from `emitParseWarnings` in packages/cli/src/commands/workflow.ts. When a workflow YAML definition contains keys the engine does not recognize (per the workflow-language constitution: YAML exposes only governable surface), the parser collects the ignored keys and the CLI prints this header followed by one line per key. The run proceeds; the extra keys are silently dropped from the engine's perspective.

Source

Thrown at packages/cli/src/commands/workflow.ts:1060

    throw new Error(
      `Error loading workflows: ${err.message}\nHint: Check permissions on .archon/workflows/ directory.`
    );
  }
}

/**
 * Print a workflow's parse warnings (keys the engine silently drops) to stderr.
 *
 * stderr rather than stdout so `--json` callers keep a parseable payload while
 * still being told; `console.warn` rather than the logger because `--json` sets
 * the log level to silent, which is exactly the case this has to survive.
 */
export function emitParseWarnings(
  parseWarnings: readonly string[] | undefined,
  workflowName: string
): void {
  if (!parseWarnings || parseWarnings.length === 0) return;
  console.warn(`Warning: '${workflowName}' declares keys the engine ignores:`);
  for (const warning of parseWarnings) {
    console.warn(`  - ${warning}`);
  }
}

/**
 * Print a deprecated workflow's removal notice (#2781) to stderr.
 *
 * Same channel as emitParseWarnings: stderr keeps `--json` stdout parseable,
 * and `console.warn` survives `--json`'s log silencing. Not gated on --quiet —
 * a user driving runs programmatically still has to learn the default they
 * picked is scheduled for removal.
 */
export function emitDeprecationNotice(workflow: WorkflowDefinition): void {
  const notice = formatDeprecationNotice(workflow);
  if (notice) console.warn(notice);
}

View on GitHub (pinned to 0773b97458)

Solutions

Read the indented lines under the header — each names an ignored key and its location.
Remove the unknown keys from the workflow YAML, or replace them with the engine-supported equivalents.
Check `.archon/workflow-language-constitution.md` and the authoring guide for the valid YAML surface.
Validate the workflow file against the current workflow schema before running.

Example fix

// before (workflow.yaml)
retries: 3
steps: []
// after
retry:
  max: 3
steps: []

Defensive patterns

Strategy: validation

Validate before calling

// Validate workflow YAML against the schema before running
import { parseWorkflowDefinition } from '@archon/workflows';
const { warnings } = parseWorkflowDefinition(yamlText);
if (warnings.length) throw new Error(`ignored keys: ${warnings.join(', ')}`);

Prevention

Lint workflow YAML against the current workflow schema in CI.
Copy keys only from the current authoring guide, not older docs or AI output.
Treat any 'keys the engine ignores' warning as a bug in your workflow file.

When it happens

Trigger: Running any workflow command whose definition (bundled, project `.archon/workflows/`, or global `~/.archon/workflows/`) parsed with non-empty `parseWarnings` — i.e. the YAML has unknown top-level or node keys.

Common situations: Hand-edited workflow YAML with typo'd keys (e.g. `retries:` instead of `retry:`); copying keys from an older or newer Archon version; following outdated documentation or AI-generated YAML with invented fields.

Related errors

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