Troubleshoot scheduled tasks

The app calls these Scheduled tasks. The CLI command screenpipe pipe, local API paths under /pipes, and configuration file pipe.md retain their technical names. Use those exact identifiers in commands and configuration.

When a scheduled task fails, debug it like a small production job: confirm the engine is alive, confirm the scheduled task has data, confirm the AI provider works, then inspect logs and permissions.

Fast triage

Check	Command or screen	What it tells you
Engine	`curl http://localhost:3030/health`	Screenpipe API is alive
Data	`curl "http://localhost:3030/search?limit=5"`	There is searchable context
Scheduled task list	`curl http://localhost:3030/pipes`	Scheduled task is installed and enabled
Logs	`curl http://localhost:3030/pipes/<name>/logs`	Last stdout, stderr, and errors
Manual run	`curl -X POST http://localhost:3030/pipes/<name>/run`	Schedule is not the blocker
Stop	`curl -X POST http://localhost:3030/pipes/<name>/stop`	Clears a stuck execution

Lifecycle

Common failures

Symptom	Likely cause	Fix
Run never starts	Scheduled task disabled or another run is queued	Enable it, stop stale runs, run manually
No useful output	Prompt did not require a durable output	Tell the scheduled task exactly where to write, notify, or summarize
”Connection refused”	Local API still booting	Wait for `/health`, then rerun
”Unauthorized”	API auth or provider key missing	Set `SCREENPIPE_API_KEY`, sign in, or update provider credentials
Empty search results	Time range too narrow or capture disabled	Widen the window and verify `/search?limit=5`
Windows terminal flashes and closes	Process crashed immediately	Open scheduled task logs or run script from PowerShell
Scheduled task sees old data only	Schedule window or stale filters	Remove filters, run manually, widen time range
Custom window not found	Exact window title differs	Search broad, then inspect stored `window_name`
Notification does not fire	Condition, integration, or OS notification setting	Test each step outside the scheduled task
Provider timeout	Model slow, batch too large, or network issue	Use faster model, add timeout, or rerun
Connection API fails	Integration disconnected or missing proxy path	Reconnect the integration and use `/connections/<id>/proxy/...`
Permission denied	Scheduled task permissions too narrow	Review the task’s `permissions` configuration

Windows scheduled task exits immediately

If a black command window appears and disappears, the scheduled task process is probably crashing before you can read the error.

Open Scheduled tasks → My tasks, select your scheduled task, and open its logs.
Run the scheduled task manually.
If the scheduled task calls a script, run that script directly in PowerShell.
Confirm pipe.md exists in the scheduled task folder and has valid frontmatter.
Confirm the local API is alive:

curl http://localhost:3030/health

Then search broadly:

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

Do not debug the schedule until manual run works.

Write prompts with debuggable outputs

Weak:

Tell me what I did today.

Strong:

Search the last 24 hours of screenpipe data.
Write a markdown summary to ~/Documents/daily-screenpipe-summary.md.
Include:
- accomplishments
- meetings
- open loops
- timeline links for the 5 most important moments
If there is no data, say which API call returned empty.

For monitoring scheduled tasks, add a “no match” behavior:

Search the last 10 minutes for the window named "Operations Dashboard".
If you find a red error banner, send a desktop notification.
If the window is missing or no error is visible, write a log line explaining which case happened.
Never send an alert unless the evidence is present in screenpipe results.

Frontmatter checklist

---
schedule: every 30m
enabled: true
timeout: 600
permissions:
  allow:
    - /search
    - /activity-summary
    - /meetings
---

Keep the schedule simple until the scheduled task works manually. Add permissions only for the APIs the scheduled task needs.

Secrets and provider auth

Do:

Keep API keys in .env next to pipe.md
Use connected app proxies when possible
Use local models through Ollama for fully local execution
Use SCREENPIPE_API_KEY when API auth is enabled

Do not:

Paste API keys into the prompt body
Ask the AI to print secrets
Grant broad write access before the scheduled task is proven

Connection proxies

Connected apps can be called without exposing secrets to the scheduled task prompt:

curl "http://localhost:3030/connections/google-calendar/events?hours_ahead=8"
curl "http://localhost:3030/connections/notion/proxy/v1/search"
curl "http://localhost:3030/connections/hubspot/proxy/crm/v3/objects/contacts"

Exact proxy paths depend on the integration. See connection reference. Start with broad search, then add filters one at a time.

curl "http://localhost:3030/search?limit=10&content_type=all"
curl "http://localhost:3030/search?limit=10&content_type=accessibility"
curl "http://localhost:3030/search?limit=10&content_type=ocr"
curl "http://localhost:3030/search?limit=10&content_type=audio"

Use content_type=all or content_type=accessibility for most app text. OCR is fallback pixel text, not the main source of screen text on platforms where accessibility data is available. When filtering by window, first inspect real stored window names from broad results. The visible title bar and stored window_name can differ. Avoid this while debugging:

curl "http://localhost:3030/search?limit=50&content_type=ocr&window_name=Exact%20Title"

Prefer:

curl "http://localhost:3030/search?limit=20&content_type=all"

Then add window_name, app_name, start_time, or end_time only after you know the data exists.

Notifications and external actions

If a scheduled task should play a sound, show a notification, send Telegram, update Notion, or call a webhook, split the debugging:

Layer	Test
Capture	Does `/search` find the condition?
Decision	Does the prompt explain why it will or will not act?
Integration	Does the notification/API call work outside the scheduled task?
Permissions	Can the scheduled task call the endpoint or command?
Schedule	Does the scheduled task run manually before relying on cron?

Make the scheduled task log every skipped action. Silent “no-op” runs are hard to debug.

When to use chat, MCP, or scheduled tasks

Job	Use
One question about recent activity	Chat
External AI assistant needs screen memory	MCP
Recurring workflow or scheduled output	Scheduled task
Structured integration with CRM/calendar/notes	Scheduled task plus connections
Local script or app integration	REST API

Collect a useful bug report

Include:

Scheduled task name and pipe.md
Schedule and whether manual run works
Output of curl http://localhost:3030/health
Output of curl http://localhost:3030/pipes/<name>/logs
AI provider and model
Whether API auth is enabled
OS and Screenpipe version

Get started

Recording and data

Scheduled tasks

Connect

Use cases

Personal and team knowledge

Workflow playbooks

Enterprise guides

Integrations

Reference

Deployment

Compare

Resources

Troubleshoot scheduled tasks

Fast triage

Lifecycle

Common failures

Windows scheduled task exits immediately

Write prompts with debuggable outputs

Frontmatter checklist

Secrets and provider auth

Connection proxies

Search filters that usually break custom scheduled tasks

Notifications and external actions

When to use chat, MCP, or scheduled tasks

Collect a useful bug report

​Fast triage

​Lifecycle

​Common failures

​Windows scheduled task exits immediately

​Write prompts with debuggable outputs

​Frontmatter checklist

​Secrets and provider auth

​Connection proxies

​Search filters that usually break custom scheduled tasks

​Notifications and external actions

​When to use chat, MCP, or scheduled tasks

​Collect a useful bug report

​Related pages

Fast triage

Lifecycle

Common failures

Windows scheduled task exits immediately

Write prompts with debuggable outputs

Frontmatter checklist

Secrets and provider auth

Connection proxies

Search filters that usually break custom scheduled tasks

Notifications and external actions

When to use chat, MCP, or scheduled tasks

Collect a useful bug report

Related pages