Troubleshooting

Context Limit Exceeded?

Fix oversized prompt failures fast so your agent can work again without losing your project momentum.

If your agent returns "context limit exceeded", it is not broken. It means the model received too much text at once (chat history + files + your new request).

Quick reality check: this is a payload-size problem, not an intelligence problem. The fix is almost always to reduce and structure context.

What usually causes it

Very long ongoing chat threads with lots of back-and-forth.
Pasting massive logs, docs, or transcripts in one message.
Asking for many tasks at once across multiple files.
Sending the same giant prompt repeatedly after a failure.

2-minute recovery flow

1) Start a fresh chat/session for this task

Don’t keep retrying inside a bloated thread. New session = clean context budget.

2) Send only the minimum context

Include objective, one key constraint, and the smallest relevant excerpt. Skip everything else.

3) Break the work into stages

Use sequence: analyze → decide → produce output instead of one giant all-in-one prompt.

4) Ask for compact outputs

Request bullets, short diffs, or a 5-point summary first. Expand only after a successful small response.

Copy/paste rescue prompt

You hit a context limit earlier. Continue this task with a compact workflow: 1) Restate my goal in 2 bullets. 2) List only the 3 most important facts you need from me. 3) If missing info is small, ask one concise question. 4) Return a short first-pass output (max 150 words). Do not request full history or large pasted logs.

Bad vs good request style

High-risk (likely to fail)

Here are 12 files and our full 3-day conversation. Review all of it, find every issue, rewrite everything, and propose strategy.

Low-risk (more reliable)

Goal: fix one section in this file. File: /docs/pricing-page.md Task: rewrite only the CTA paragraph for clarity. Constraints: keep tone friendly, max 90 words. Return: before/after text only.

High-friction edge cases

Long chat inertia: Even a short new message can fail if thread history is huge. Move to a fresh session.
Multi-file overload: Ask the agent to process one file at a time and confirm completion after each.
Large logs: Share only the error block + 20 lines before/after, not entire logs.
Cross-surface confusion: Dashboard, DM, and server channel are separate contexts. Keep recovery in one surface.

Advanced edge cases (when it still fails)

Attachment pileups: Multiple large files/images in one turn can exceed budget even if your text is short. Send one file at a time.
"Summarize everything" prompts: Asking for broad synthesis across many sources spikes token use. Ask for a table of contents first, then process sections.
Stale giant handoffs: Pasting old handoff blocks in every message silently bloats each turn. Reuse a compact 5-line brief instead.
Error-loop escalation: If the exact same compact request fails twice in a fresh session, switch to a smaller subtask and include only one artifact.

Known-good compact handoff (copy/paste)

Goal: [one sentence] Current artifact: [single file/path/link] Success criteria: [2 bullets] Hard constraints: [max 2 bullets] Now do only Step 1 and keep output under 120 words.

Avoid the retry trap: repeatedly resending the same oversized request usually makes things worse and wastes tokens.

Prevention rules that actually work

Use a fresh session for each major objective.
Keep one message focused on one concrete output.
Store long references in files; pass paths + targeted excerpts.
Ask for a short plan first, then approve step-by-step execution.

Bottom line: Context-limit errors are normal at scale. Smaller scoped prompts and staged execution will fix most failures in minutes.