shareAI-lab/learn-claude-code · error · WorkflowInputError

cached agent output failed schema validation: {err}

Error message

cached agent output failed schema validation: {err}

What it means

On resume, agent() short-circuits with the journal's cached output, but when a schema is supplied the cached value is re-validated with SimpleJsonSchema before being returned. If validation fails, WorkflowInputError('cached agent output failed schema validation: ...') is raised, because a stale cached result that no longer matches the current schema would poison the resumed run.

Source

Thrown at s16_workflow_runtime/code.py:469

    def log(self, message):
        """Emit a workflow_log progress line."""
        self.task.progress_event("workflow_log", message=message)

    async def agent(self, prompt, schema=None, label=None, phase=None):
        """Spawn one subagent. With a schema, force StructuredOutput + validate
        (retry once). On resume, a cached key short-circuits the run."""
        label = label or (prompt[:24] + "...")
        self._limits.claim_agent()
        if self.budget.remaining() <= 0:
            raise WorkflowInputError("token budget exceeded")

        key = self.journal.key("agent", label, prompt, schema)
        cached = self.journal.cached(key)
        if cached is not MISS:
            if schema is not None:
                ok, err = SimpleJsonSchema(schema).validate(cached)
                if not ok:
                    raise WorkflowInputError(
                        f"cached agent output failed schema validation: {err}"
                    )
            self.task.progress_event("workflow_agent", label=label,
                                     phase=phase or self._phase, status="cached")
            return cached

        async with self._limits.semaphore:
            run = await asyncio.to_thread(
                self.runner.run, prompt, schema, label
            )
            result = run.value
            tokens = run.tokens

        if schema is not None:
            ok, err = SimpleJsonSchema(schema).validate(result)
            if not ok:
                retry = await asyncio.to_thread(
                    self.runner.run,

View on GitHub (pinned to 985456f4ad)

Solutions

1. Revert the schema to the exact definition used when the original run recorded the entry, then resume again.
2. Start a fresh run (new runId) instead of resuming, so every agent output is regenerated against the new schema.
3. Delete or rename the journal for that runId in STORE so the offending cached entry is not replayed (loses all caching for that run).

Example fix

# before
FINDINGS_SCHEMA = {"type": "object", "required": ["findings", "summary"]}
# resume fails on cached entries lacking "summary"

# after
FINDINGS_SCHEMA = {"type": "object", "required": ["findings"]}
# matches the schema used when the journal was written

from s16_workflow_runtime import SimpleJsonSchema
ok, err = SimpleJsonSchema(NEW_SCHEMA).validate(cached_entry)
if not ok:
    start_fresh_run()  # do not resume with a changed schema

def cache_matches_schema(journal, key, schema) -> bool:
    cached = journal.cached(key)
    if cached is MISS:
        return False
    ok, _ = SimpleJsonSchema(schema).validate(cached)
    return ok

try:
    result = await workflow_call(resume_from_run_id=rid)
except WorkflowInputError as e:
    if "cached agent output failed schema validation" in str(e):
        result = await workflow_call()  # fresh run, no resume
    else:
        raise

When it happens

Trigger: Resuming a run (resume_from_run_id) with a schema that was changed (fields added/renamed, types tightened) since the original run recorded the journal entry for that agent label/prompt/schema key.

Common situations: Editing a workflow's FINDINGS_SCHEMA between the original run and the resume; deploying a new schema version and resuming an old runId; hand-editing the journal file in STORE/.runtime.

Related errors

• resume journal not found for {run_id}
• invalid resume journal record at line {line_number}
• agent({{schema}}) invalid output: {err}
• resume runId does not match workflow meta
• resume args do not match the original run

AI-assisted analysis of shareAI-lab/learn-claude-code@985456f4ad (2026-08-14). Data as JSON: /api/errors/f1f5ef81758e87c1. Report an issue: GitHub.