> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenpipe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# troubleshoot screenpipe: install, permissions, and pipes

> Fix common screenpipe issues including installation errors, screen and microphone permissions, missing audio, pipe failures, and MCP connection problems.

{/* https://screenpi.pe */}

## start here

| symptom                                        | first check                                              | deeper guide                                  |
| ---------------------------------------------- | -------------------------------------------------------- | --------------------------------------------- |
| app says free after purchase                   | sign out/in with purchase email                          | [FAQ](/faq)                                   |
| cannot find receipt                            | account billing area and purchase email                  | [FAQ](/faq)                                   |
| desktop timeline missing after CLI install     | install desktop app, not only CLI                        | [getting started](/getting-started)           |
| app opens but data is empty                    | `curl http://localhost:3030/health` and wait 1-2 minutes | [API recipes](/api-recipes)                   |
| AI tool cannot see screenpipe                  | MCP config, Node 18+, app running                        | [MCP server](/mcp-server)                     |
| pipe fails or hangs                            | pipe logs, provider auth, permissions                    | [pipe debugging](/pipe-debugging)             |
| Windows command window flashes during pipe run | pipe exits immediately; check logs                       | [pipe debugging](/pipe-debugging)             |
| meeting transcript is empty                    | microphone, system audio, transcription engine           | [meeting intelligence](/meeting-intelligence) |
| `/api/search` returns 404                      | use `/search` on `localhost:3030`                        | [API recipes](/api-recipes)                   |
| privacy question                               | local/cloud path and enabled toggles                     | [privacy data flow](/privacy-data-flow)       |
| connected app fails                            | OAuth callback, token, proxy path                        | [connection reference](/connection-reference) |

<img src="https://docs.screenpi.pe/public/app-screenshots/settings-storage.png" alt="screenpipe storage settings" width="1200" />

## installation & startup

### installed the CLI but cannot find the timeline

`npx -y screenpipe@latest record` starts local recording and the API. it does not give you the desktop timeline UI by itself.

if you want the visual timeline, pipe store, settings, chat, and guided permissions, install the desktop app from [screenpi.pe/onboarding](https://screenpi.pe/onboarding).

after installing the desktop app:

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

**macOS:**

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

**Windows:**

* 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

**Linux:**

* 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

try this before reinstalling:

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.

if the app still says free after purchase, include the purchase email and the currently signed-in email when contacting support.

### screenpipe is running but not capturing

check the health endpoint:

```bash theme={null}
curl http://localhost:3030/health
```

if it returns an error:

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

if health returns OK but search returns no results:

* 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

the local screenpipe endpoint is:

```bash theme={null}
curl "http://localhost:3030/search?limit=5"
```

not `/api/search`.

common checks:

* `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"`

use [API recipes](/api-recipes) for copy-paste examples.

### search only finds old results

if recent results are missing:

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?

use app recording filters when you want to include or exclude specific apps, windows, or URLs. for strict work-hour logic, create a pipe that checks the current time and exits outside your desired window, or configure recording/schedule settings when that control is available in the app.

## 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

on Windows 11 24H2, some USB and communications-class microphones can expose formats that look valid but produce unusably quiet audio. if transcripts are empty or audio is around silent:

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

if you notice gaps in transcription or missing audio segments, the transcription queue is likely full and screenpipe is dropping segments to prevent the system from freezing.

**causes:**

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

**fixes (in order of effectiveness):**

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

if the issue persists, check logs: settings → pipes → view logs to see "dropping audio segment" warnings.

### bluetooth headphone audio quality drops

this is a macOS limitation, not a screenpipe bug. when any app opens a bluetooth microphone, macOS switches from A2DP (high quality) to HFP (phone quality).

**fix:** go to **settings → recording** → switch input to your MacBook's built-in microphone. screenpipe still captures your voice, and your bluetooth audio quality stays high.

note: AirPods don't have this issue — Apple uses a proprietary codec.

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

if you want to record only certain applications (like Teams meetings) and exclude everything else:

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

this is useful for compliance, privacy (avoid recording unrelated work), or reducing storage usage. your recorded meetings and transcriptions are searchable via the API as normal.

note: with included windows, screenpipe pauses capture when the app loses focus. this is intentional — if you want to capture even when focused on another window, use the broader "all windows" setting instead.

***

## chat & AI interactions

### chat hangs or stops responding

if your chat window freezes, try these fixes in order:

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 a faster, lighter model in your configured provider, check logs for "timeout" errors

### chat messages disappear

if assistant replies vanish when navigating away, **update to the latest version** — this message persistence bug was fixed. if you are behind, reinstall screenpipe to get the latest version.

### AI model connection fails

1. verify subscription active: [openai.com](https://openai.com) (ChatGPT Plus/Pro) or [claude.ai](https://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

this usually means the pipe started and crashed immediately.

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`.

include the log output when asking for help. "the command window flashes" is the symptom; the useful error is usually in the pipe log or the script output.

### 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

debug the pipeline in pieces:

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 -y 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
* use cloud archive to offload and restore older data ([learn more →](/cloud-archive))

### can I store data on a NAS or external drive?

you can back up `~/.screenpipe/` to external storage. be careful with active database and media writes on slow or unreliable network drives; they can make the app feel broken or risk corruption.

for active long-term retention, prefer [cloud archive](/cloud-archive) or a stable local disk plus backup. if you do use a NAS, test recording, search, restart, and recovery before relying on it.

### 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](/privacy-data-flow).

**multi-monitor setups**: screenpipe captures all monitors simultaneously. with 2-3+ displays, memory usage can double or triple because each monitor frame is processed independently.

**fixes for multi-monitor setups:**

1. reduce capture rate: settings → capture rate → try 0.5 FPS instead of 1 FPS. this is the most effective optimization for multi-monitor systems
2. close the timeline view when not actively using it — it buffers video frames from all monitors in memory
3. if you only need one display: in the UI, disable or hide unused monitors in the settings → recording section
4. monitor your actual usage: `curl http://localhost:3030/vision/list` shows active monitors. each additional monitor increases baseline memory by 50-200 MB depending on resolution

### 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

some buttons disable themselves while the local engine is cold. wait for:

```bash theme={null}
curl http://localhost:3030/health
```

then retry sync, pipe run, search, or MCP setup.

***

## privacy & PII

### how is personal data protected?

screenpipe redacts the values you type into form fields — passwords, card numbers, secrets — on-device by default, before data is stored or sent. detected PII is also redacted in stored text columns at rest, not only at AI-query time. on top of that default, you have these options:

| feature                        | what it does                                                                   | where                                    |
| ------------------------------ | ------------------------------------------------------------------------------ | ---------------------------------------- |
| form-field redaction (default) | masks passwords, card numbers, and secrets on-device before storing or sending | on by default                            |
| local AI PII removal           | redacts sensitive data before selected AI workflows see it                     | settings → privacy → AI PII removal      |
| privacy filter (enclave mode)  | uses a confidential enclave to redact text for cloud AI                        | settings → privacy → privacy filter mode |
| ignored windows                | prevents screenpipe from recording specific apps (password managers, banking)  | settings → recording → ignored windows   |

the safest setup: keep the defaults on, enable **AI PII removal**, ignore your password manager window, and use local Ollama or disabled cloud media.

### 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.

the local model runs on your machine — no data leaves your computer. the first run may be slow as the model loads; subsequent searches are faster.

### 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

it does NOT redact:

* 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

### what redaction is automatic vs. optional

form-field values (passwords, card numbers, secrets) are redacted on-device by default, before data is stored or sent, and detected PII is redacted in stored text columns at rest.

the broader **AI PII removal** and **privacy filter (enclave mode)** options are toggles you enable in settings — turn these on for extra coverage of names, emails, phone numbers, and other categories across AI workflows. image PII removal for screenshots is also a separate toggle.

***

## still stuck?

1. check the [FAQ](/faq) for quick answers
2. search [GitHub issues](https://github.com/screenpipe/screenpipe/issues) — someone may have hit the same problem
3. [join our Discord](https://discord.gg/screenpipe) — 10k+ members who can help debug

when asking for help, include:

* 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