[Python SDK 0.1.7] Linux bridge: UserMessage + JPEG → run error ~40s (Windows OK, same API key)

Support Bug Reports
, ,
1

Describe the Bug

Where does the bug appear?

Cursor Python SDK (cursor-sdk bridge on a Linux server), headless Agent via AsyncClient.launch_bridge().

Environment

  • Package: cursor-sdk 0.1.6 → upgraded to 0.1.7 (issue unchanged)
  • OS: Debian Linux (VM-16-5-debian), Python 3.11.2, x86_64
  • Model: composer-2.5 (also tested kimi-k2.5 — same failure)
  • Same Cursor API key on Linux cloud and Windows dev machine
  • Image: instrument-photo.jpg, ~546 KB JPEG (not SVG)
  • SDKImage.from_file → UserMessage(text=long_prompt, images=[…]) → agent.send() → run.wait()

Steps to Reproduce

  1. On Linux, pip install cursor-sdk==0.1.7 in a venv.
  2. Launch ephemeral bridge with AsyncClient.launch_bridge(workspace=…).
  3. Create agent with composer-2.5; send long text prompt (~2541 chars) plus one JPEG in UserMessage.images.
  4. run.wait() returns status=error after ~40–50s, streamedLen=0, generic Agent run failed: run-xxx, empty conversation_json().
  5. Control (same Linux, same key): remove images → 3/3 success.
  6. Control (Windows 11, Python 3.13, same key, same JPG): 5/5 success.

Expected Behavior

Agent completes with a normal text reply; vision input should work per Python SDK documentation.

Actual Behavior

  • status=error ~40s after send, no assistant output
  • conversation_json() often
  • Probe and text-only long prompts succeed on the same Linux host (not a connectivity issue)

Operating System

Linux

Version Information

  • Package: cursor-sdk 0.1.6 → upgraded to 0.1.7 (issue unchanged)
  • OS: Debian Linux (VM-16-5-debian), Python 3.11.2, x86_64

For AI issues: which model did you use?

Model: composer-2.5 (also tested kimi-k2.5 — same failure)

For AI issues: add Request ID with privacy disabled

Failed run IDs (Linux, with image)

  • run-bfff22d1-14b4-4f78-b1b0-20accf711f47 (0.1.7)
  • run-c3765655-e676-41eb-b0aa-b9fc05b4dfa0
  • run-cb73a430-1a65-4442-9b33-33029ebcc3a1
  • run-9fadb50f-3a13-499c-9bfd-415d6a94fa6d (0.1.6)durationMs ~38000–47000, streamedLen 0, conversationJson “”

Successful run ID (same Linux, no image, promptLen 2541)

  • run-1e11df6c-4ef2-4da8-9633-9257ec8c4164

Additional Information

Controlled Experiments (Linux cloud)

Case promptLen image Result
probe 20 0 3/3 OK
full, no image 2541 0 3/3 OK
full, with JPEG 2541 1 0/3 FAIL
composer + image n=5 2541 1 0/5 FAIL
kimi-k2.5 + image n=5 2541 1 0/5 FAIL
upgrade 0.1.6 → 0.1.7 2541 1 still 0/3 FAIL

Conclusion: correlates with UserMessage.images on Linux, not model, not prompt text alone.

Does this stop you from using Cursor

No - Cursor works, but with this issue

6

Hi Tiago, this is a really well-isolated report, thank you. The controlled experiments make the picture clear.

What you’re hitting looks like a genuine bug in the SDK’s local bridge that’s specific to image payloads on Linux. Two things are going on: the run is failing in the local bridge before it reaches our backend, and separately the bridge is swallowing the real underlying error and only handing back a bare status=error with an empty conversation, which is why it looks so opaque. The error-masking part is something we’ve already been working on improving.

To pin down the image-specific failure, two quick things would help a lot:

  1. Re-run the failing image case with CURSOR_SDK_LOG=debug (CURSOR_SDK_LOG=debug python your_script.py) and share anything extra it prints - any stack, error name, or request ID. (Troubleshooting docs)

  2. Try a much smaller image (resize the same photo to well under ~50KB) on the same Linux host. If the small one succeeds while the 546KB one fails, that tells us the failure is tied to image payload size, which matches what we’re seeing.

I’m getting this in front of the team that maintains the SDK. Since text-only and Windows both work for you, sending images through a local agent on Windows is a viable stopgap in the meantime.

For reference, the image API and troubleshooting toggle are documented here: Python SDK — sending images · Troubleshooting.