Workflow & Runtime Errors

Workflow errors happen during execution — Claude is running, the file system is accessible, but something in the task pipeline breaks. A git merge gets stuck in a retry loop, an npm install creates version conflicts, a sub-agent hangs forever, or you hit the API rate limit. This page groups every workflow-and-runtime error we have documented so you can identify the failure mode and jump to the fix.

How Workflow Errors Differ from System Errors

System errors block Claude from reaching the environment (permissions, PATH, network). Workflow errors happen after Claude is running — the environment is fine, but the task itself is producing failures. The distinction matters because the fixes are different: system errors need OS-level changes, while workflow errors need prompt adjustments, task restructuring, or billing changes.

Errors in This Category

Git Merge Conflict Loop

Claude encounters a merge conflict, tries to resolve it by editing the conflict markers, but its "fix" introduces new syntax errors. The next merge attempt fails, Claude tries again, and the cycle repeats five or more times without progress.

Typical message: Conflict in file X. Attempting to resolve... followed by Merge failed. Retrying... in a loop.

Quick check: Is Claude repeatedly editing the same file? If yes, stop it immediately — manual resolution is faster.

Full fix: Git Merge Conflict Loop →

NPM Dependency Hell

Claude ran npm install package-name without checking your existing package.json version constraints. It installed a React 19 library into a React 18 project, triggering a cascade of peer dependency errors.

Typical message: ERESOLVE unable to resolve dependency tree or peer dependency conflict

Quick check: Did the error appear right after Claude installed a new package? Check git diff package.json to see what changed.

Full fix: NPM Dependency Hell →

Sub-Agent Timeout

You launched a complex task with parallel sub-agents ("Research these 10 companies"), but one or more agents got stuck. They may be looping, rate-limited, or blocked by a network hiccup. The parent task hangs waiting for results that never arrive.

Typical message: Sub-agent execution timed out or Waiting for agent... (forever)

Quick check: How many sub-agents did you spawn? More than 5 at once is a common cause of timeouts.

Full fix: Sub-Agent Timeout →

Rate Limit Exceeded (429)

You sent too many messages in a short window (RPM limit), hit your daily token cap (TPD limit), or spawned too many sub-agents that all hit the API simultaneously and triggered a burst limit.

Typical message: 429: Too Many Requests or Rate limit exceeded. Please try again later.

Quick check: Check your billing page — did you hit a monthly hard cap? If not, it is likely a burst limit that clears in 60 seconds.

Full fix: Rate Limit Exceeded (429) →

General Workflow Debugging Order

When a workflow error occurs, follow this sequence:

Stop the agent. Do not let a looping task run — it wastes tokens and can corrupt files. Hit Ctrl+C in the CLI or click Stop in the UI.
Assess the damage. Run git status and git diff to see what Claude changed before the failure. If files are in a bad state, git stash or git checkout to revert.
Identify the failure mode. Is it a loop (same action repeated)? A conflict (version mismatch)? A timeout (agent hung)? A limit (quota hit)?
Apply the targeted fix. Use the specific guide linked above for your error type.
Restart with a refined prompt. Add constraints like "if you cannot resolve this in 3 attempts, stop and ask me" to prevent the same failure.

Preventing Workflow Errors Before They Happen

Most workflow errors share the same root cause: too much autonomy on a complex task without guardrails. Build these guardrails into your prompts:

Batch size limits: "Do 5 at a time, not all 20 at once."
Attempt limits: "If a merge conflict persists after 2 resolution attempts, stop and ask me to resolve manually."
Version checks: "Before installing any package, check if it is compatible with React 18."
Time budgets: "If a sub-task takes more than 3 steps, stop and report 'Not Found' — do not keep searching."
Small PRs: "Commit after every logical unit of work, not after 50 files of changes."

These constraints feel verbose, but they prevent 80% of workflow errors and cost zero tokens compared to a stuck loop that runs for 10 minutes.

Types of Workflow Errors

Workflow errors fall into several distinct categories. Understanding which type you are dealing with determines the fix.

Loop Errors

The agent repeats the same action — editing a file, running a command, retrying a merge — without making progress. Each iteration may introduce new problems. The git merge conflict loop is the canonical example, but loops also appear in test-fix cycles (Claude fixes a test, the fix breaks another test, it reverts, the original test fails again) and in build-error cycles where each fix introduces a new syntax error.

Identifying feature: The agent's output messages repeat with slight variations. You see "Attempting to resolve..." followed by "Failed. Retrying..." three or more times.

Dependency and Version Errors

The agent installs or upgrades a package without checking compatibility, producing a cascade of peer dependency conflicts. These errors are common when Cowork decides a library "should be updated" or installs a new package at the latest version without checking your project's version constraints.

Identifying feature: The error appears immediately after an npm install, pip install, or equivalent command. The error message references version numbers or peer dependencies.

Timeout and Hang Errors

A sub-agent or tool call does not return. The parent task waits indefinitely. This happens most often with parallel sub-agents that hit rate limits simultaneously, or with network-dependent operations (fetching a URL, querying an API) that stall without a timeout.

Identifying feature: The output stops at "Waiting for agent..." or "Executing tool..." and does not progress for more than 60 seconds. No error message appears.

Rate Limit and Quota Errors

The API rejects requests because you exceeded a limit — requests per minute, tokens per day, or concurrent sub-agent count. These are the easiest to diagnose because the error message is explicit (429: Too Many Requests).

Identifying feature: A clear HTTP 429 status code in the error output.

State Corruption Errors

The agent leaves files in an inconsistent state — half-applied refactor, a git branch with uncommitted changes from a failed merge, a package.json modified but package-lock.json not updated. These errors do not always produce an error message; they surface later when you try to build or run tests.

Identifying feature: No immediate error, but git status shows unexpected changes or the build fails on the next run with errors that do not match the current code.

Debugging Workflow Issues

When a workflow error occurs, follow this step-by-step debugging process. The order matters — skipping steps leads to missed root causes.

Step 1: Stop the Agent Immediately

Do not wait to see if it recovers. A looping agent wastes tokens and can corrupt files. Hit Ctrl+C in the CLI or click Stop in the desktop UI. If the agent is a sub-agent, stopping the parent task kills all children.

Step 2: Capture the Current State

Before changing anything, record what the agent did:

git status
git diff --stat
git log --oneline -5

Save this output. If you need to file a bug report or ask for help, this state snapshot is essential.

Step 3: Identify the Error Category

Look at the last 10–15 lines of agent output and classify the error:

Signal	Category
Repeated "Retrying..." messages	Loop error
`ERESOLVE` or `peer dependency`	Dependency error
"Waiting for agent..." with no progress	Timeout/hang
`429` or `Rate limit`	Rate limit error
No error, but files are inconsistent	State corruption

Step 4: Revert to a Known Good State

If the agent left files in a bad state, revert before debugging further:

# If changes are uncommitted
git stash push -m "broken workflow attempt"

# If the agent committed broken changes
git reset --hard HEAD~1

# If you are not sure what changed
git diff HEAD --stat

Never debug on top of a corrupted state. You will end up chasing errors that the agent introduced rather than the original problem.

Step 5: Reproduce the Error in Isolation

Try to reproduce the failure with a minimal prompt. If the agent failed on "refactor the entire auth module and update all tests," try "refactor src/auth/login.ts only." If the minimal prompt succeeds, the issue was task complexity — break the task into smaller pieces. If the minimal prompt also fails, the issue is environmental and needs a different fix.

Step 6: Apply the Targeted Fix

Use the specific guide for your error category:

Loop errors: add attempt limits to your prompt.
Dependency errors: specify version constraints before installing.
Timeout errors: reduce parallelism or add explicit time budgets.
Rate limit errors: check your billing page and reduce concurrent sub-agents.
State corruption: always commit before starting a complex task.

Prevention: Designing Robust Workflows

Most workflow errors are preventable through prompt design. The goal is to constrain the agent's autonomy so it cannot enter failure states.

Structure Tasks as Small, Verifiable Steps

Instead of one large prompt ("refactor the authentication system"), break the task into a sequence:

"Read src/auth/ and list all files with their responsibilities."
"Refactor src/auth/login.ts to use the new session API. Do not touch other files."
"Run npm test -- auth and report results."
"If tests pass, commit with message 'refactor: login to new session API'. If tests fail, show me the errors and stop."

Each step has a clear input, a clear output, and a verification gate. The agent cannot drift into a loop because each step is bounded.

Add Explicit Failure Conditions

Tell the agent what to do when it gets stuck:

"If you encounter a merge conflict that you cannot resolve in 2 attempts, stop and report the conflict. Do not attempt a third resolution."

"If npm install fails with a peer dependency error, do not attempt to force-install. Stop and show me the error."

"If a sub-task takes more than 5 tool calls, stop and report 'Task too complex for single pass.'"

These instructions give the agent permission to fail gracefully instead of looping.

Commit Frequently

Instruct the agent to commit after each logical unit of work:

"After completing each file refactor, run git add <file> && git commit -m 'refactor: <description>'. Do not batch multiple files into one commit."

Frequent commits create checkpoints. If the agent corrupts state on file 8, you revert to the commit after file 7 — not back to the start.

Use a `.coworkignore` File

Prevent the agent from touching files it should not modify:

.env
.env.local
*.pem
*.key
package-lock.json
yarn.lock

Lock files in particular cause state corruption when the agent modifies package.json but does not correctly update the lock file.

Limit Parallelism for Sub-Agents

If you are spawning sub-agents, cap the concurrency:

"Process these 10 items with at most 3 sub-agents running at the same time. Wait for one to complete before starting the next."

This prevents rate limit errors and makes timeout failures easier to isolate.

Recovery: Getting Back on Track

When a workflow error has already happened and the agent has left your project in a broken state, follow this recovery sequence.

Step 1: Assess the Damage

Run a full state check:

git status
git diff --stat
git log --oneline -10
npm test 2>&1 | tail -20

Determine whether the damage is confined to uncommitted changes (easy to revert) or committed (requires a reset).

Step 2: Revert to the Last Known Good Commit

If the agent made commits that broke the build:

# Find the last commit where tests passed
git log --oneline -20

# Reset to that commit, keeping changes as uncommitted
git reset --soft <good-commit-hash>

# Review the changes
git diff --stat

# If the changes are salvageable, fix them manually
# If not, discard everything
git reset --hard <good-commit-hash>

Step 3: Clean Up Partial Artifacts

The agent may have left partial artifacts: half-written files, a corrupted node_modules, or a stuck git merge state.

# Clear a stuck merge state
git merge --abort

# Reinstall dependencies cleanly
rm -rf node_modules package-lock.json
npm install

# Remove untracked files the agent created
git clean -nfd  # dry-run first to see what will be deleted
git clean -fd   # actually delete

Step 4: Document What Went Wrong

Write a brief note (in a WORKFLOW_NOTES.md file or a commit message) describing the failure:

What was the task?
What error occurred?
At what step did the agent fail?
What prompt change would prevent it next time?

This note becomes the basis for improved prompts on future tasks.

Step 5: Restart with a Refined Prompt

Start a new session with a more constrained prompt. Incorporate the failure conditions you identified:

"Refactor src/auth/login.ts. If you encounter any error you cannot fix in 2 attempts, stop and report. Commit after the refactor is complete and tests pass."

The refined prompt should be more restrictive than the original — you are trading speed for reliability, which is the correct tradeoff after a failure.

Related Errors

Workflow errors overlap with other error categories. If your issue does not match the workflow patterns above, check these related pages:

Git Merge Conflict Loop — The most common loop error, with specific resolution steps.
NPM Dependency Hell — Detailed fix for peer dependency conflicts and version mismatches.
Sub-Agent Timeout — How to handle hung sub-agents and prevent them with concurrency limits.
Rate Limit Exceeded (429) — Token and request quota errors, including how to check your billing page.
Context & Logic Errors — Errors caused by context window limits rather than execution failures. These can trigger workflow errors (a context-drifted agent is more likely to enter a loop).
System & Permission Errors — Errors where Claude cannot reach the environment at all. If the agent cannot even start, this is the category to check.

Share this article