troubleshoot screenpipe: install, permissions, and pipes

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.

​

start here

​

installation & startup

​

installed the CLI but cannot find the timeline

1. open screenpipe.
2. grant screen recording and accessibility permissions.
3. wait 1-2 minutes.
4. verify data with curl "http://localhost:3030/search?limit=5&content_type=all".

​

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)
• if the embedded browser or timeline is blank, install or repair Microsoft Edge WebView2 Runtime and restart screenpipe

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

​

login loop, failed to load user, or wrong account

1. quit screenpipe completely.
2. reopen the app and sign out if possible.
3. sign back in with the same email used for purchase or trial setup.
4. make sure your default browser can open the login callback.
5. temporarily disable VPN/proxy if the callback never returns.

​

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 screen text search is working: curl "http://localhost:3030/search?limit=1&content_type=all"
• try content_type=accessibility and content_type=all before narrowing to OCR-only searches
• check included/ignored windows filters so you are not excluding the app you are testing

​

API and timeline confusion

​

/api/search returns 404

curl "http://localhost:3030/search?limit=5"

• curl http://localhost:3030/health
• curl "http://localhost:3030/search?limit=5&content_type=all"
• curl "http://localhost:3030/search?limit=5&content_type=accessibility"
• curl "http://localhost:3030/search?limit=5&content_type=audio"

​

search only finds old results

1. confirm recording is still active in settings.
2. check whether the app/window is ignored.
3. search without start_time, end_time, app_name, or window_name filters first.
4. if a pipe uses a schedule, remember it may only search its schedule window.
5. restart screenpipe if the UI is stale but the API is healthy.

​

can I capture only work hours?

​

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"

​

windows microphones record silence or near-silence

1. switch the input to the Windows system default microphone.
2. unplug phantom devices such as dock stubs or controller adapters.
3. test another USB port or direct connection instead of a dock.
4. restart screenpipe and run curl "http://localhost:3030/search?content_type=audio&limit=1".
5. include the exact device name when reporting the issue.

​

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)

​

record only specific apps (e.g. Teams, Zoom)

1. screen capture: go to settings → recording → included windows and add the app name (e.g., Teams, Zoom). screenpipe will only capture these windows, even if you switch away briefly
2. audio devices: go to settings → recording and select only the devices you need — for example, just your microphone and system audio, deselecting other inputs
3. test it: open Teams and verify the timeline shows only Teams content. try opening other apps — they shouldn’t appear in the recording

​

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

​

Windows command window opens and closes when a pipe runs

1. open settings -> pipes.
2. select the pipe and open logs.
3. run the pipe manually.
4. check that pipe.md exists in the pipe folder and has valid frontmatter.
5. if the pipe calls a script, run that script from PowerShell so the error stays visible.
6. verify the local API with curl http://localhost:3030/health.

​

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"
5. confirm the prompt says what to do when no data is found, so the pipe does not silently guess

​

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
• start with manual run; only debug the schedule after manual run works

​

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"
• search with content_type=all before narrowing to accessibility, ocr, or audio
• remove window_name filters until you confirm the exact window title stored by screenpipe

​

pipe notifications, sounds, or Telegram messages do not fire

1. confirm the pipe starts.
2. confirm screenpipe search returns the condition you expect.
3. test the notification or Telegram/API call outside the pipe.
4. reconnect the integration if tokens expired.
5. make the prompt write a log line when it decides not to notify.

​

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 →)

​

can I store data on a NAS or external drive?

​

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)
• local PII models can use several GB while active, then unload after idle time. see privacy data flow.

​

timeline or owned browser is blank on Windows

1. install or repair Microsoft Edge WebView2 Runtime.
2. close screenpipe completely and reopen it.
3. check whether other WebView2 apps on the machine render.
4. if this only happens after sleep/wake, restart screenpipe and include logs in the report.

​

engine is still starting

curl http://localhost:3030/health

​

privacy & PII

​

how is personal data protected?

​

enable local PII redaction

1. go to settings → privacy.
2. toggle AI PII removal on.
3. choose a redaction policy: default is credentials-only (catches API keys, tokens, SSNs, credit cards). you can also choose strict to redact names, emails, and phone numbers.
4. for image protection: toggle image PII removal separately if you want screenshots redacted before image workflows.
5. restart screenpipe if you changed settings.

​

what does PII redaction remove?

• credentials-only mode (default): API keys (OpenAI, Anthropic, Stripe, etc.), SSNs, credit card numbers, tokens, private keys, database connection strings with passwords
• strict mode: all of above plus names, emails, phone numbers, IP addresses, URLs with credentials

• general text (even if it sounds like it might be sensitive)
• partial matches (e.g., an email-like pattern without valid formatting)
• structured data in code or config files that isn’t in a recognized credential format

​

PII redaction is optional, not automatic

​

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
• whether API auth and LAN access are enabled
• microphone/audio device name, if audio is involved
• relevant pipe logs or error messages