# Atlas error: Task failed or Task cancelled from a subagent > Read the child's error text in the message, it is passed through verbatim, then open the subagent's session to inspect its transcript rather than guessing from the summary line. Atlas task fails with the subagent's own error text, or with Task cancelled, because TaskTool inspects the finished job status: an error status re-throws the child's error message, falling back to "Task failed", and a cancelled status throws "Task cancelled". The fix is to read the child's error text in the message, since it is passed through verbatim, then open the subagent's session to inspect its transcript rather than guessing from the summary line. ## Symptom The task tool fails with the subagent's own error text, or with: Task cancelled. The parent session reports the failure on one line and the subagent produces no result. ## Cause TaskTool inspects the finished job status: an error status re-throws the child's error message, falling back to "Task failed", and a cancelled status throws "Task cancelled", so the parent surfaces whatever the child ended with. ## Fix 1. Read the child's error text in the message; it is passed through verbatim. 2. Open the subagent's session to inspect its transcript rather than guessing from the summary line. 3. If you cancelled the parent session, the child is cancelled too; that is expected. 4. Re-run the task with a narrower prompt if the child ran out of context or tools. ## Why does Atlas report Task failed or Task cancelled Atlas reports Task failed or Task cancelled because TaskTool inspects the finished job status of the subagent. In the 2026 source, an error status re-throws the child's error message and falls back to "Task failed" when there is none, while a cancelled status throws "Task cancelled". The two messages describe different endings, and telling them apart is the first diagnostic step. Task cancelled means the job was stopped, not that it broke. A subagent error, by contrast, arrives as the child's own error text, because TaskTool re-throws it rather than replacing it with a generic string. The literal words "Task failed" only appear as a fallback, when the child errored without producing a message of its own. So a bare "Task failed" is itself information: the subagent failed and said nothing useful about why, which is your cue to go read its transcript. ## How to read the real error from an Atlas subagent Read the child's error text in the Atlas message. TaskTool passes it through verbatim, so the string you see in the parent session is the subagent's own error, not a paraphrase. The generic Task failed appears in exactly 1 situation, as a fallback when the child produced no message of its own. Treat the surfaced text as the primary evidence. If the child failed on a tool call, a permission denial, or a bad path, that error is what you are looking at, and it usually names the tool and the offending argument directly. Because every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, a subagent can fail on a rule that the parent session never encounters, which is one of the more common surprises. Match the error text to the tool it came from before you change anything about the task prompt. ## How to open the subagent session transcript in Atlas Open the Atlas subagent's session to inspect its transcript rather than guessing from the summary line. The parent session shows 1 line, either the child's error text or Task cancelled, while the child's session holds the full sequence of tool calls and model turns that led there. The summary line is a verdict, not an explanation. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, and each of those subagents keeps its own transcript. Read it end to end: you will see which files the child opened, which searches it ran, where it lost the thread, and which tool call produced the failure. Guessing from the one-line summary is how developers end up rewriting a prompt that was never the problem, when the actual failure was a missing language server or an unreachable endpoint several steps in. ## Why did my Atlas subagent get cancelled An Atlas subagent shows Task cancelled when its finished job status is cancelled rather than errored, and TaskTool treats those 2 statuses differently. If you cancelled the parent session, the child is cancelled too, and that is expected behavior, not a bug in the task tool. Cancellation propagates downward. Interrupting the parent stops the children it launched, because a subagent exists to serve the parent's turn and has nothing to return to once that turn is gone. When you see Task cancelled and you remember hitting the interrupt, the loop is closed and there is nothing to debug. When you see Task cancelled and you did not cancel anything, look at what else stopped the session, since the child did not error on its own. The distinction is worth checking before you spend time on a prompt rewrite. ## How to re-run a failed Atlas task successfully Re-run the Atlas task with a narrower prompt if the child ran out of context or tools. 1 subagent handed a scope it cannot finish will exhaust its budget and end with an error status, which TaskTool then re-throws into the parent session as the child's own error text. Narrowing works in two directions. Reduce the surface area of the question, asking about one module rather than an entire service, and reduce the tool surface the child needs, pointing it at files you have already located instead of asking it to find them from scratch. Both shrink the work per subagent. If several narrow tasks would cover the ground, run them: Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so several small tasks are usually a better shape than one that keeps failing. ## FAQ ### how to debug Task failed in Atlas Read the child's error text in the message, because TaskTool passes it through verbatim, then open the subagent's session to inspect its transcript rather than guessing from the summary line. ### what does Task cancelled mean in Atlas Task cancelled means the subagent's job status was cancelled rather than errored. If you cancelled the parent session, the child is cancelled too, and that is expected. ### why does Atlas show a generic Task failed with no details "Task failed" is the fallback TaskTool uses when the child errored without producing an error message of its own. Open the subagent's session transcript to see what actually went wrong. ### does cancelling an Atlas session cancel its subagents Yes. If you cancelled the parent session, the child is cancelled too. Cancellation propagates from parent to subagent, and Task cancelled is the expected result. ### how do I fix an Atlas subagent that runs out of context Re-run the task with a narrower prompt. Reduce the scope of the question and point the subagent at files you have already located instead of asking it to search from scratch. ### is the Atlas subagent error message the real error Yes. TaskTool re-throws the child's error message verbatim, so the text in the parent session is the subagent's own error, not a rewritten summary. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/task-failed-or-cancelled Source of truth: aeo_pages row `/resources/troubleshooting/task-failed-or-cancelled` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.