You wake up, open your laptop, and find the Background Agent you launched the night before has stopped — halfway through the task. No error notification. No clear message about what went wrong. Just a frozen thread and a half-finished codebase.
This is one of the more frustrating aspects of working with Background Agents. Unlike inline sessions where you can watch errors happen in real time, Background Agents fail silently. By the time you notice, hours may have passed with nothing accomplished.
This article breaks down the five most common reasons Background Agents stop prematurely, along with concrete diagnostic steps and prevention strategies for each.
Why Background Agents Stop
Blaming it on "something went wrong" and rerunning the task without understanding the cause usually means the same thing happens again. Almost every premature stop falls into one of these five categories:
- Session timeout: Processing exceeded the time limit (typically 2–3 hours)
- Context exhaustion: The AI's context window filled up and it couldn't continue the task
- Network disconnection: A sleep cycle, Wi-Fi drop, or VPN disconnect interrupted API communication
- File conflict: The agent tried to write to a file you (or Git) were editing simultaneously
- Error loop failure: The same error repeated enough times that the agent auto-stopped
Session timeout and context exhaustion account for the majority of unfinished Background Agent runs. Network disconnection is the next most common. Addressing these three will eliminate most of your incomplete sessions.
Diagnosis: Understanding Where It Stopped
After finding a stopped Background Agent, open the agent thread in the side panel and check these three things:
[Diagnostic checklist]
1. Last message content → What was it trying to do?
2. Error messages → Red text often pinpoints the cause directly
3. Timestamp → When it stopped helps narrow down the reason
If the last message cuts off mid-sentence with something like "I've been working on...", that points to timeout. Messages mentioning "Context length exceeded" or "Token limit" indicate context exhaustion. Repeated identical error messages suggest an error loop.
Running git log to check the timestamp of the last commit also tells you exactly how far the agent got before stopping — invaluable for deciding where to restart.
Fix 1: Task Splitting to Avoid Timeouts
Background Agents have session time limits. Based on experience, tasks longer than 2–3 hours are at risk. Large-scale refactors, full test suite generation, or "just handle everything" instructions are the most common culprits.
The fix is straightforward: break the task into milestone-sized phases.
# Good example (phase-based)
"Phase 1 only: Standardize error handling in src/api/.
Once complete, run git commit and stop. That's all for this session."
# Bad example (too broad)
"Read the entire src/ directory, refactor everything,
write tests, and update the documentation."Scoped instructions complete far more reliably than open-ended ones. Since I started splitting long tasks into 90-minute phases, incomplete Background Agent sessions have become rare.
When chaining phases, leave a note in the commit message describing what the next phase should tackle. The next agent session can pick up cleanly from there.
Fix 2: Scope Specification to Prevent Context Exhaustion
When working on large codebases, the AI can exhaust its context window by trying to read everything before starting. The fix is to specify exactly which files and directories to focus on from the start.
# Good (explicit scope)
"Focus only on files in src/components/Button/.
Consolidate the prop type definitions.
Do not touch any other directories."
# Bad (forces the AI to read widely)
"Read through the entire project and consolidate all type definitions."
For frequently referenced paths and architectural decisions, AGENTS.md is your best tool. Writing down the key files and constraints there means the agent doesn't have to discover them by reading through the codebase each time. See Diagnosing and Fixing Context Drift in Antigravity for strategies on managing context more effectively.
Fix 3: Protecting Against Network Disconnections
If the API connection drops — because your Mac went to sleep, Wi-Fi briefly disconnected, or your VPN timed out — the Background Agent stops immediately. For long overnight sessions, this is a real risk.
On macOS, preventing sleep during a session is simple:
# Prevent system sleep (press Ctrl+C to stop)
caffeinate -i &
# For a session with a known duration (e.g., 3 hours)
caffeinate -i -t 10800 &A more robust approach, though, is commit-driven design. If you instruct the agent to commit at meaningful checkpoints, a network drop mid-session doesn't erase your progress — you just pick up from the last commit.
# AGENTS.md example
## Commit policy
- Run git commit after completing each feature or function
- Commit message format: "agent: [summary of what was completed]"
- Keep each commit to 10 files or fewerFix 4: Branch Isolation to Eliminate File Conflicts
If you're editing files while a Background Agent is also working on them, write conflicts can occur and the agent may stop. This is especially likely when you want to continue developing while the agent handles a parallel task.
The cleanest solution is to have the agent work on its own branch:
# Example instruction
"Create a new branch named feature/refactor-auth.
Perform the src/auth/ refactoring entirely on that branch.
Do not touch main under any circumstances."With this pattern, you continue developing on main while the agent works in isolation on its feature branch. When it's done, review and merge as a PR. For more production-grade patterns, Background Agent Advanced Production Guide covers team workflows in depth.
Fix 5: Setting Exit Conditions to Break Error Loops
A Background Agent that retries the same failing operation indefinitely is a subtle but costly problem. Hours pass, nothing gets done, and when you finally notice, you're left either with a stopped agent and lost work, or a commit history full of identical failed attempts.
The fix is to tell the agent upfront what to do when it's stuck:
# Example instruction
"If the same error occurs 3 or more times in a row,
stop retrying immediately.
Write the error details and the last attempted fix
to a file called agent-debug-notes.md, then exit."This single instruction prevents overnight loop disasters. The debug notes file tells you exactly what it got stuck on, so the next session can be targeted directly at the root cause. AI Agent Error Recovery Design Patterns goes deeper on building resilient agent workflows.
Diagnostic Flow When the Cause Is Unclear
When you genuinely can't tell why it stopped, work through this sequence:
1. Read the last message in the agent thread
→ Timeout / context exhaustion / error loop covers most cases
2. Check git log for the last commit timestamp
→ Tells you how far it got before stopping
3. Run git diff HEAD to see uncommitted changes
→ Shows what it was working on when it stopped
4. Check terminal logs if available
→ Network errors and file access failures sometimes appear here
These four steps identify the root cause the vast majority of the time.
Restarting After a Stopped Session
When a Background Agent stops, don't just re-run the original instruction verbatim. Take a moment to diagnose first, then adapt.
If the agent got through partial work before stopping, check for uncommitted changes and commit them manually before starting the next session. You can also review any debug notes the agent left behind — they often contain the exact error that caused the stop.
Then, when restarting, be more specific than the original instruction:
# Restarted session instruction (example)
"The previous session completed up to authentication.ts.
Continue from there: implement the token refresh logic in auth/refresh.ts.
Scope: auth/ directory only. Commit when done."This specificity reduces the risk of the agent trying to re-do already-completed work or accidentally overwriting the progress from the previous session.
If you're running long workflows regularly — overnight test generation, large codebase migrations, documentation passes — it's worth setting up a lightweight status file that the agent updates as it completes each phase:
# agent-status.md (updated by the agent)
## Session log
- [2026-04-26 01:30] Phase 1 complete: src/api/ error handling standardized
- [2026-04-26 02:15] Phase 2 complete: unit tests updated for api/ changes
- [2026-04-26 03:01] Phase 3: IN PROGRESS — updating integration testsThis gives you a clear audit trail of what ran successfully, and makes restarting a stopped session much less guesswork.
Two Things to Try Today
Completely eliminating Background Agent failures isn't realistic, but you can reduce them dramatically. Start with just these two changes today:
- Split any task longer than 90 minutes into phases, and have the agent commit at the end of each phase
- Add to your AGENTS.md: "If the same error repeats 3 times, stop and write debug notes to agent-debug-notes.md"
These two habits will meaningfully improve your Background Agent completion rate. If you're new to Background Agents, Background Agent Getting Started Guide is the right starting point before applying these techniques.