Troubleshooting
Common failures when running Cursor Agent in Burp.
Agent won’t start / “command not found”
| Check | Fix |
|---|---|
agent missing | Install the Cursor Agent CLI and confirm agent --help in the same environment Burp will use (native shell or WSL). |
| Logged out | Run agent login (or your org’s auth flow), then retry. |
| Windows PATH | Use launch profile WSL if agent only exists inside WSL. Prefer absolute Linux paths. |
| GUI Burp on Linux/macOS | GUI apps often miss login-shell PATH. Set an absolute path in Settings or Custom override. |
Confirm Launch preview under Settings → General. See launch.md.
Windows: CreateProcess error 267 (invalid directory)
Cause: ProcessBuilder cwd set to a Linux path while launching wsl.exe.
Fix: Keep the WSL launch profile; do not force a Linux cwd for the Windows process. Session cwd (Agent-side) can still be /home/... inside WSL — that is separate from process cwd.
Permission banner never appears / tools always denied
- Confirm policy is Ask (or Allow all if you intended auto-approve).
- Switch to the Cursor Agent Suite tab — the inline Allow/Deny strip lives above the composer.
- Waiting too long times out to Deny.
- Allow safe denies shells and other mutators by design.
Chat title keeps changing after reload
Current builds only accept the Agent’s auto-title while the chat is still a placeholder (General Chat). If you still see retitles on an old build, reload the latest JAR. Explicit burpai-rename always asks for Allow.
Agent “forgot” context but the transcript is still there
After extension unload or process death, Burp keeps messages. The next send tries to resume the ACP session; if that fails, ACP starts a new session, the chat shows a system notice, and that send can include a resume briefing (Settings → Resume briefing: compact or full).
Resume stays on the error/notice strip so you can re-brief the Agent anytime. Prefer that over pasting the whole chat.
Switching Burp projects while the extension stays loaded also stops Agent processes and reloads that project’s saved chats. Chats stay per project; use Export / Import to move them (sessions.md).
Tool output looks clipped / can’t scroll the chat
- Long commands should wrap inside the Command box (no horizontal “wall”).
- Tall output: scroll inside the Output box; at the edges, wheel continues the main transcript.
- If you scrolled up mid-run, the chat should stay put while new content grows below. Jump-to-latest (chevron) re-arms follow when a turn is busy.
MCP tools missing
- Settings → MCP: Link Cursor MCP (read-only) if servers live in Cursor’s
mcp.json, or edit Own list. - Create a new chat after changing MCP so the new session picks them up.
- Confirm the Burp MCP (or other server) works from the Cursor Agent CLI outside Burp.
- Confirm launch profile matches which OS’s
mcp.jsonyou expect (mcp.md).
Extension errors / empty tab
- Confirm class name:
io.zamdevio.burpai.BurpaiExtension - Confirm JAR is the shadow artifact:
burp-cursor-agent-*-all.jar - Check Burp’s Extensions output / Event log for load errors (wrong JDK for Burp itself is separate from build JDK 21).
Still stuck?
- Reproduce with a one-line prompt in a fresh chat.
- Note launch profile (native / WSL / override), OS, and whether
agentworks in a terminal. - Copy the Error strip text (sanitized) from the Chat tab.
Related
- Install · Launch · Sessions · Permissions