troubleshooting

Documentation Index

Fetch the complete documentation index at: https://docs.screenpi.pe/llms.txt

Use this file to discover all available pages before exploring further.

​

installation & startup

​

screenpipe won’t start

• grant screen recording permission: System Settings → Privacy & Security → Screen Recording → enable screenpipe
• grant accessibility permission: System Settings → Privacy & Security → Accessibility → enable screenpipe
• if you see “app is damaged”, right-click the app → Open (bypasses Gatekeeper on first launch)

• run as administrator on first launch
• if Windows Defender blocks it, click “More info” → “Run anyway”
• ensure .NET runtime is installed (screenpipe installer usually handles this)

• install dependencies: sudo apt install tesseract-ocr libxcb1
• grant screen capture permissions for your display server (X11 or Wayland)

​

screenpipe is running but not capturing

curl http://localhost:3030/health

• make sure screen recording permission is granted
• restart the app
• check if another instance is already running on port 3030

• wait 1-2 minutes — screenpipe needs time to capture and process frames
• check that your display is listed in settings → monitors
• verify OCR is working: curl "http://localhost:3030/search?limit=1"

​

audio & transcription

​

no audio being captured

• check settings → recording — make sure at least one device is selected
• on macOS: grant microphone permission in System Settings → Privacy & Security → Microphone
• verify audio is being recorded: curl "http://localhost:3030/search?content_type=audio&limit=1"

​

audio drops out during calls or long meetings

• transcription can’t keep up with the incoming audio (especially with large batch sizes or slower hardware)
• multiple audio devices selected simultaneously
• transcription engine is overloaded (too many complex tasks running)

1. reduce batch size: settings → recording → audio chunk duration — try lowering from default (30-40s) to 10-15s. smaller batches process faster and drop less audio
2. switch to faster transcription: settings → AI models → try whisper-tiny or whisper-base instead of whisper-large-v3-turbo (trades accuracy for speed)
3. disable unused audio devices: settings → recording → uncheck devices you don’t need — recording one device instead of multiple reduces queue pressure
4. use cloud transcription: switch to deepgram or screenpipe-cloud for remote processing, which doesn’t block your local system
5. reduce system load: close heavy apps or run screenpipe on a machine with better CPU/RAM

​

bluetooth headphone audio quality drops

​

transcription is inaccurate

• switch to a better engine: settings → AI models → whisper-large-v3-turbo (most accurate)
• set your language explicitly in settings (auto-detect is slower and less accurate)
• reduce background noise
• use a better microphone
• try deepgram or screenpipe-cloud for cloud-based transcription (highest accuracy)

​

chat & AI interactions

​

chat hangs or stops responding

1. restart screenpipe — closes stalled message queues
2. check health: curl http://localhost:3030/health — if it fails, backend is stuck
3. verify you have data — screenpipe needs screen/audio history; wait 1-2 minutes after startup
4. verify AI provider connection — settings → model selector. for ChatGPT/Claude, sign out/back in
5. reduce load — disable unused pipes (settings → pipes), switch to faster model (gpt-4o mini), check logs for “timeout” errors

​

chat messages disappear

​

AI model connection fails

1. verify subscription active: openai.com (ChatGPT Plus/Pro) or claude.ai (Claude Pro)
2. sign out/in: settings → model selector → sign out, restart, sign back in
3. if still failing, your tokens expired — try again

​

pipes

​

pipe runs but produces no output

1. check logs: go to settings → pipes → click your pipe → view logs
2. make sure your prompt includes concrete instructions to write output or send notifications
3. test manually: click “run” in the pipe UI and watch the logs in real-time
4. verify screenpipe has data to work with: curl "http://localhost:3030/search?limit=5"

​

pipe doesn’t run on schedule

• make sure the pipe is enabled (toggle is on in settings → pipes)
• check that the schedule format is correct: every 30m, every 2h, daily, or a cron expression
• only one pipe runs at a time — if another pipe is running, yours will wait in the queue

​

pipe fails with AI errors

• check your AI provider is configured: settings → AI settings
• if using screenpipe cloud: make sure you’re signed in
• if using your own API key: verify it’s valid and has credits
• if using ChatGPT/Claude subscription: try signing out and back in to refresh tokens
• check the pipe logs for the specific error message

​

pipe can’t find screen data

• make sure screenpipe is actively recording (check health endpoint)
• the pipe only searches within its schedule interval — if schedule is “every 30m”, it only looks at the last 30 minutes
• verify data exists for the time range: curl "http://localhost:3030/search?start_time=30m+ago&limit=5"

​

MCP & AI connections

​

MCP not connecting to Claude/Cursor

1. verify screenpipe is running: curl http://localhost:3030/health
2. restart Claude Desktop / Cursor after adding the MCP config
3. test the MCP server directly: npx @modelcontextprotocol/inspector npx screenpipe-mcp
4. check that Node.js >= 18 is installed: node --version

​

Claude/Cursor says “no results” when asking about screen

• make sure screenpipe has been running long enough to capture data
• try a broader query: “what apps have I been using?” instead of very specific text
• check that screen recording permissions are granted

​

ChatGPT connection not working

• sign out and sign back in (settings → model selector → sign out)
• make sure your ChatGPT subscription is active
• try restarting the screenpipe app

​

performance

​

screenpipe using too much CPU

• reduce capture FPS: settings → capture rate (default 1 FPS is usually fine)
• exclude heavy apps from capture: settings → recording → ignored windows
• on older machines, use whisper-tiny instead of whisper-large-v3-turbo

​

screenpipe using too much disk space

• screenpipe uses ~30 GB/month at 1 FPS — this is normal
• reduce capture rate in settings
• data is stored in ~/.screenpipe/data/ — you can delete old recordings
• future: cloud archive offloads older data (learn more →)

​

screenpipe using too much RAM

• typical usage is ~600 MB RAM
• if it’s using significantly more, restart the app
• close the timeline view if you’re not using it (it loads video frames)

​

still stuck?

1. check the FAQ for quick answers
2. search GitHub issues — someone may have hit the same problem
3. join our Discord — 10k+ members who can help debug

• your OS and version
• screenpipe version (shown in settings)
• output of curl http://localhost:3030/health
• relevant pipe logs or error messages