Subagent failures and diagnostics

DataMind Oda can hand part of a task to a subagent, and that run can fail, be refused, or be stopped before it finishes. This page is the catalogue of the messages that tell you so, and how to read them. How delegation works is in Delegating work to subagents; what a settled subagent sends is in Subagent settlement and results.

When a run does not complete

A run that does not complete brings back three parts: a headline that names the ending, a Diagnostic: line, and the text the subagent produced before it ended, under Partial output before the run ended:. The headline tells you the run's stop reason:

• A run that completes has no headline: its result is the subagent's final text.
• How an ending becomes a stop reason: a normal end reads completed; a stopped run reads aborted, and a cancelled run is not a failure, so it carries no diagnostic; a run that outgrows its context window reads max-tokens, like any other token-limit ending; a refusal, or a blocked subagent, reads refusal; anything else reads error.
• A one-shot background run reports through its job instead: a stopped one reads as killed with your reason; see Background subagents and job collection.
• For what to do next after a stopped or failed run, see Continuable subagents.

The diagnostic line

The Diagnostic: line is the run's own account of what went wrong, written to be safe to show: it never carries the subagent's raw output, file contents, paths, task text, environment values or credentials. What it names is where the run stopped (a stage) and what kind of problem it was (a category).

• A long diagnostic is cut to a size cap and ends with [diagnostic truncated], so a missing tail is not a missing problem.
• One category value worth knowing: child-disposed, in an SDK diagnostic, marks a subagent that was closed from its own side before it finished.

What a failure line reads like, backend by backend

The exact wording depends on the backend the subagent ran on. The ACP, Claude Code and Codex pages list their stages and categories in full: ACP, Claude Code, Codex.

• The line can carry extra facts after the category: a stop reason:, an HTTP status (Codex), an exit code, or a signal.
• The in-process backends do not use these lines: a failure there reads as the shared result headlines above.
• A run cancelled while it is still starting leaves nothing behind and reports one line naming where it was stopped: subagent request was aborted before the ACP child started (ACP); subagent request was aborted before SDK startup, subagent request was aborted before the SDK child started or subagent cancelled before the SDK child initialized (SDK); subagent-codex: request was aborted before app-server startup or subagent-codex: request was aborted before run publication (Codex); subagent request was aborted before child publication (an in-process subagent).

When a request is refused

Each message below tells you a request was not allowed and names its own reason. The delivery rules themselves are in Continuable subagents.

Starting and resuming

• subagent limit reached (active child limit: <n>); wait for an existing child to finish or complete this work with the current agents: every active place is taken. The limit is shared across the chat's tree of subagents and is eight by default; a place frees when a subagent finishes. See Subagent settings.
• subagent "<id>" already exists: the id was already taken, so nothing started; delegate again.
• subagent "<id>" has no supported continuation state and cannot be resumed; choose a different target: the saved record cannot be read by this version of Oda; start a new subagent for the work. See Subagent settlement and results.
• Bringing a subagent back also needs this installation's session records: a resume or a follow-up is refused when its session persistence or session query piece is missing, and the refusal names the missing piece.
• subagent parent "<id>" is being disposed; the child was not established: the parent was already closing down when the start ran, so nothing started.
• agent preset "<name>" needs a preset roster, and this deployment composes none: bringing back a subagent that runs under a named preset is refused when this installation builds no preset list.

Messages and interrupts

• message delivery requires the exact live sender agent: a message goes only between live neighbours in the tree, and the sender was not one.
• agent "<id>" is not a resident continuable child and cannot send to parent "<id>": a subagent that is not resident tried to message its parent.
• interrupting "<id>" requires the exact live ancestor agent: only a live ancestor may interrupt a subagent.
• agent "<id>" cannot interrupt itself: a subagent cannot interrupt its own turn.
• subagent "<id>" belongs to another parent session or subagent "<id>" is not a live descendant of agent "<id>": the caller is not part of this subagent's live family line.
• subagent "<id>" activation is being disposed; the message was not delivered: the subagent was already winding down; once its intake had closed, the same refusal reads subagent "<id>" activation is being disposed; the message was not accepted.

Stops and closing

• selected child teardown requires the exact live parent agent: closing a chosen subagent needs its exact live parent to ask.
• subagent "<id>" is not a direct child of agent "<id>": a close was asked from outside the direct relationship.
• continuable subagents are draining; the operation was not admitted: subagents are being closed right now, so a new operation of this kind is not accepted while that runs. A variant names the parent whose part is draining; ask again once the closing has finished.

Listing

• subagent listing was cancelled: reading the list was cancelled before it finished, and nothing about the subagents changed.
• Reading the list needs this installation's session query service, its subagent catalog, its projections registry and its session store; when one of them is missing, the list is refused and names the missing piece.

When a request from the app fails

Prompts and interrupts can also be driven from the app itself. A failed request there carries a stable code; these are the codes and their messages.

When closing a subagent goes wrong

A subagent that does not close cleanly does not read as a clean ending: Oda reports its run as an error instead of a completion, withholds its output, and records the problem as a teardown failure.

Closing continues past a failure: when a chat is archived, its running subagents are stopped one at a time, and one that fails to stop is noted while the others still stop. See Chat with Oda.

Questions, answered

Does a cancelled run count as a failure?

No. A cancelled run settles as aborted: the headline reads subagent run was cancelled and no diagnostic is attached. A run you stop from the chat reads the same way; a stopped one-shot background run reports through its job as killed instead, with the reason you gave.

What does subagent run ended abnormally (<reason>) mean?

The run ended for a kind outside the four standard stop reasons, and Oda names that kind in brackets. Treat it like a failure: read the Diagnostic: line and the partial text to see what the subagent managed to do before it stopped.

What do stage and category in a diagnostic mean?

The stage says where the run stopped, and the category says what kind of problem it was. For example, stage: prompt; category: remote-limit says the run stopped while the task was being worked on, because the far side reported one of its own limits.

Why does a diagnostic end with [diagnostic truncated]?

Because it was longer than its size cap, so it is cut short and marked. The stage, the category and the beginning of the account are still there; only the tail was dropped.

Can I retry work a failed run did not finish?

Yes, start a new delegation for the part that is left. A continuable subagent can also be brought back and sent what remains, and a run that stopped at its token limit keeps its partial text so you can see what is missing.

What does it mean that subagents are draining?

Some subagents are being closed right now. Closing a subagent closes any subagents it started first, and while a closing runs, a new operation of that kind is held back instead of being accepted part-way; the refusal reads continuable subagents are draining; the operation was not admitted. Ask again once the closing has finished.

What does subagent listing was cancelled mean?

Reading the list of a chat's subagents was cancelled before it finished. Nothing about the subagents themselves changed: it is a reading that stopped, not a subagent failing. Ask to list again.

Why was a subagent not established because its parent was closing?

The parent was already closing down when the start ran, so no subagent was started: the refusal reads subagent parent "<id>" is being disposed; the child was not established. Nothing half-started is left behind; start the work again if it is still needed.

Why was a follow-up refused while a subagent is winding down?

The subagent was already closing, and one that is closing cannot take a message. The refusal says whether the message was not delivered, or, once its intake had closed, not accepted; nothing was delivered by it.

What happens when a subagent does not close cleanly?

Its run is reported as an error instead of a completion, and its output is withheld rather than returned as a result; the problem is recorded as a teardown failure. When this happens while a chat is archived, the other subagents still stop.