Troubleshooting

Troubleshooting

Language: English · فارسی

Problem	Cause and fix
config error: env var X is not set	The file uses ${X} but it is not exported. Set it, or add the secret to the CI job's env:.
No alert when a site is down	It must fail down_after times in a row (default 2). Check events, an active maintenance window (UTC), and stderr for notify failed.
notify failed: ... No such file or directory: 'shoutrrr'	No usable Docker and no binary on PATH. Start Docker, install the binary (pulsecheck init does it) or set shoutrrr_bin.
Docker is installed but the binary is used	docker info fails for your user (daemon stopped, no permission). Fix that or set shoutrrr_bin: docker.
notify failed: plus a shoutrrr error	Wrong URL or token. Run shoutrrr verify --url ... and pulsecheck test-notify.
Same DOWN alert again and again	State was lost between runs (cache evicted, runners without shared cache, container without a volume). Keep state_file on persistent storage.
Site flaps between up and degraded	slow_ms is close to the normal response time. Raise it.
Ping always fails in Docker/CI	Install iputils-ping; some containers also forbid raw sockets. Use type: tcp instead.
HTTPS certificate error	The check fails with the error shown in the alert. Fix the certificate; there is no option to skip verification.
Scheduled GitHub run stopped	Schedules pause after 60 days without repository activity. Re-enable in the Actions tab.
Vercel endpoint answers 401	CRON_SECRET is unset or the Authorization: Bearer … header does not match it.
Vercel answers 500 … state store missing	Add Upstash Redis (vercel integration add upstash/upstash-kv) or set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.
Vercel deploy fails on the cron expression	Hobby accepts one run per day only. Use 0 0 * * *, or call the endpoint from GitHub (see Serverless).
notify failed: 'xyz://' is not supported here	On Cloudflare only the built-in senders work (telegram, discord, slack, ntfy, gotify, pushover, ...); Vercel downloads the real shoutrrr for everything else. For other services use the CLI, CI or cron mode.
skipped, type 'tcp' is not supported on this platform	Cloudflare runs HTTP checks only; Vercel also skips ping.
Cloudflare run stops with "exceeded CPU time"	The Free plan gives 10 ms CPU per cron run. Use the Paid plan.
Cloudflare KV write errors after some hours	Free KV allows 1,000 writes per day; a 1-minute cron needs 1,440. Use 2+ minutes or the Paid plan.
config error: ...: unknown key(s) [...]	A key is misspelled or does not exist. The message names the key and where it is.
No certificate warning	ssl_warn_days is only for https sites, and the certificate must expire in fewer days than the value. It also does not run on Cloudflare.
Reminders do not repeat	remind_every is in minutes and starts after the first down alert; alerts during a maintenance window are dropped.
no config found. Run \pulsecheck init``	There is no ./pulsecheck.yml and no ~/.config/pulsecheck/pulsecheck.yml. Run pulsecheck init or pass -c FILE.
env var X is not set although I filled .env	The .env must sit next to the config file and the line must be X=value (empty values count as not set). pulsecheck env shows which are still empty.
pulsecheck init says crontab not found	Install cron (sudo apt install cron), or use --no-cron and a systemd timer.
OpenTelemetry: otel export failed: HTTP 4xx	Wrong endpoint or auth header. The endpoint is the base URL (for example port 4318); /v1/metrics and /v1/logs are added for you.
An ip_version: 6 site is always down	This machine or runner has no IPv6 connectivity, or the host has no AAAA record. Try curl -6 -I <url> from the same place. GitHub-hosted runners may not have IPv6, so use cron on your own server for IPv6 checks.
skipped, ip_version is not supported on Cloudflare	Cloudflare's fetch picks the address family itself. Run IPv6 checks from the CLI, cron or Vercel.

Debug tip: uv run pulsecheck run --force prints one line per site with status, time and error.