Python SDK Local Agent returns ERROR after streaming valid output

[trick736_little]

Where does the bug appear (feature/product)?

Cursor SDK

Describe the Bug

On Windows, a Python cursor-sdk Local Agent starts successfully and enters RUNNING. It streams a parseable JSON response for several minutes, but the terminal result becomes ERROR with an empty result field.

The final streamed status contains:
[internal] unable to open database file

However, RunResult.result is empty, so the failure details are not available from the terminal result.

In one run, approximately 51,000 characters of assistant output were streamed and successfully parsed into 10 module records before the ERROR status. The run still consumed 161,907 total tokens.

This is an initial Local Agent run, not a Cloud Agent follow-up run.

Steps to Reproduce

1. On Windows, install cursor-sdk 0.1.8 with Python 3.14.
2. Create a Local Agent with model composer-2.5 and a writable local cwd.
3. Send a long structured-output prompt and consume messages through run.messages().
4. Observe normal RUNNING status, assistant text chunks, and usage events.
5. Call await run.wait().

Actual result:

• streamed assistant output is present and can be valid JSON;
• terminal status is ERROR;
• RunResult.result is empty;
• streamed status detail is: [internal] unable to open database file.

The issue reproduces with max_concurrent_modules=1 and a 600-second SDK timeout, so it is not caused by application-level parallelism or a client timeout.

Expected Behavior

The run should finish successfully when it has produced a complete valid response.

If it cannot finish, RunResult should include a structured error with an error code, message, request ID, and the database path or underlying reason. The SDK should make it possible to distinguish an execution failure from a finalization/persistence failure after assistant output has already been produced.

Operating System

Windows 10/11

Version Information

cursor-sdk: 0.1.8
Python: 3.14
Local Agent mode
Cursor Desktop version: N/A / not used directly

For AI issues: which model did you use?

composer-2.5

For AI issues: add Request ID with privacy disabled

No Request ID is exposed by the Python SDK for this Local Agent run.

agent_id: agent-0e5c970d-fb5c-4c87-8c9f-1245e4511340
run_id: run-15332a17-b225-40c1-bc5e-47a7d8202761

Additional Information

This resembles the diagnostic-gap aspect of:

Cloud Agents API: follow-up runs accepted but end in ERROR with no error payload

Where does the bug appear (feature/product)? Cloud Agent (GitHub, Slack, Web, Linear) Describe the Bug Where does the bug appear? Cloud Agents API — POST /v1/agents/{agentId}/runs Summary Follow-ups on a completed cloud agent are accepted (HTTP 201) and go CREATING → RUNNING → ERROR after a few minutes. GET /v1/agents/{id}/runs/{runId} returns error: null and no result. The initial run on the same agent finished successfully. Related to follow-up 404 thread, but we get 201 + run ERROR, not 40…

The underlying scenario is different: this is a Windows Local Agent initial run, not a self-hosted Cloud Agent follow-up.

Please clarify which database Local Agent is trying to open, whether its path can be configured, and whether Windows file locking, antivirus scanning, permissions, or bridge state can cause this failure.

Does this stop you from using Cursor

Sometimes - I can sometimes use Cursor

[deanrie]

Hey, thanks for the detailed report. I can answer your questions directly.

What database this is. This is the Local Agent local on-disk store that keeps history and checkpoints. By default it uses SQLite files under %USERPROFILE%\.cursor\... in WAL mode. The symptom matters: SQLITE_CANTOPEN shows up not at startup, but mid-run, when SQLite needs to reopen the WAL sidecars (store.db-wal / store.db-shm) to commit. That’s why the run streams fine at first, then fails later.

Can you change the path or storage. Yes. In LocalAgentOptions you can set store. As a workaround for this issue, try switching from SQLite to a JSONL store (store={"type": "jsonl", "root_dir": ...}), since it doesn’t use SQLite and should avoid this failure.

Could this be caused by Windows. Yes, that’s the most likely trigger. SQLITE_CANTOPEN in the middle of a run on an already opened DB usually means it couldn’t open the WAL sidecar files. First things to check:

• Exclude %USERPROFILE%\.cursor from your antivirus real-time scanning.
• Make sure %USERPROFILE% isn’t redirected or synced via OneDrive.
• Check you have write permissions for the store directory.

About RunResult not returning a structured error (code, message, request id, root cause). That’s a known gap in the Python SDK. Right now the failure is only visible in the streaming status. It’s on our radar, but I can’t share an ETA.

Let me know if switching to the JSONL store or adding the AV exclusions helped, and which cursor-sdk version you’ll test on.