coleam00/Archon · error · Error

Node '${node.id}' has persist_session: true but resolved pro

Error message

Node '${node.id}' has persist_session: true but resolved provider '${provider}' does not support sessionResume. Remove persist_session, or use a provider with sessionResume capability.

What it means

A node declaring persist_session: true requires the resolved provider to support sessionResume, since persistence is meaningless without resumable sessions. The check runs against the live provider instance's getCapabilities() (not the static registry) so it also catches providers resolved from .archon/config.yaml defaults; when the capability is missing, the executor throws with an actionable message.

Source

Thrown at packages/workflows/src/dag-executor.ts:10499

                  'dag.session_provider_boundary_fresh'
                );
              }
            }

            // Strictly opt-in: on only when the node sets persist_session (or inherits the
            // workflow-level persist_sessions default) and doesn't opt out via context:'fresh'.
            // A parallel-layer node CAN still use persist_session — it just doesn't share
            // with siblings. Same predicate gates the scope-artifact mirror below.
            const usesPersistedScope = nodeUsesPersistedScope(node, ctx.workflowPersistSessions);

            if (usesPersistedScope) {
              // Runtime capability guard via the resolved provider instance (catches the
              // case where provider was resolved from .archon/config.yaml defaults).
              // Uses the instance's getCapabilities() rather than the static registry so
              // tests can substitute mock providers with different caps without registering.
              const caps = ctx.deps.getAgentProvider(provider).getCapabilities();
              if (!caps.sessionResume) {
                throw new Error(
                  `Node '${node.id}' has persist_session: true but resolved provider '${provider}' does not support sessionResume. Remove persist_session, or use a provider with sessionResume capability.`
                );
              }
              if (ctx.persistScopeKey && !hasNamedSessionResume) {
                try {
                  const persisted = await ctx.deps.store.getWorkflowNodeSession({
                    workflow_name: ctx.workflowName,
                    node_id: node.id,
                    scope_key: ctx.persistScopeKey,
                    provider,
                  });
                  if (persisted) {
                    resumeSessionId = persisted.provider_session_id;
                    // workflow_events is broader-scoped and longer-lived than the
                    // node-session table. A session ID can resume a conversation, so we
                    // store only an 8-char prefix here — enough for observability without
                    // leaving a resumable artifact in the event log.
                    const sessionIdPreview = `${persisted.provider_session_id.slice(0, 8)}…`;

View on GitHub (pinned to 0773b97458)

Solutions

Remove persist_session: true from the node if session continuity is not needed
Switch the node (or the config default) to a provider with sessionResume: true, e.g. claude
Implement sessionResume in the custom/mock provider's getCapabilities() if it genuinely supports sessions
Log the resolved provider for the node to confirm which provider the guard saw (it may come from config defaults, not the node field)

Example fix

// before
- id: draft
  prompt: "..."
  persist_session: true
  provider: simple-llm
// after: drop persistence or use a resumable provider
- id: draft
  prompt: "..."
  provider: claude
  persist_session: true

Defensive patterns

Strategy: validation

Validate before calling

const caps = ctx.deps.getAgentProvider(resolvedProvider).getCapabilities();
if (node.persist_session && !caps.sessionResume) throw new Error(`${resolvedProvider} lacks sessionResume; remove persist_session or switch provider`);

Type guard

function canPersistSessions(caps: ProviderCapabilities): boolean {
  return caps.sessionResume === true;
}

Try / catch

try {
  await engine.run(workflow);
} catch (err) {
  if (err instanceof Error && err.message.includes('does not support sessionResume')) {
    // drop persist_session or change the provider/default config
  } else throw err;
}

Prevention

Only add persist_session when the provider explicitly supports resume
Remember provider resolution order: node field > aiProfile > config defaults — check what actually resolves
In tests, ensure substituted mock providers declare sessionResume when nodes persist sessions

When it happens

Trigger: A node sets persist_session: true while its resolved provider (node field, AI profile, or config default) reports sessionResume: false in getCapabilities(); common with mock/test providers or newly added providers lacking session support.

Common situations: Adding persist_session to a node while the global config default provider has no session support; tests substituting a mock provider without sessionResume; provider alias resolving to a different implementation than expected.

Related errors

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