Troubleshooting¶
Start with flarehound doctor: it checks the configuration, what each token can reach (naming any missing permission), the plan's capabilities, the heartbeat and the archive in one go.
FlareHound logs to stderr; in Docker use docker compose logs -f flarehound. Secrets are redacted from all log output. If the container shows unhealthy, the watch loop's heartbeat is stale — see the log.
Startup errors¶
| Message (abridged) | Fix |
|---|---|
environment variable CF_API_TOKEN is empty |
Export the read token, and pass it to the container. |
zones[0].zone_id … is not a 32-char hex Cloudflare zone ID |
Copy the zone ID from the zone's Overview page. |
account_id … (required to watch Workers) |
Set cloudflare.account_id or remove workers. |
schedule.intraday_interval must be a whole number of hours |
Use 1h, 2h, … |
schedule.intraday_offset must be within [0, 1h) |
E.g. 7m. |
schedule.daily_report_at … must be HH:MM |
E.g. "08:00", or "" to disable. |
notify.slack_webhook_url_env names X, but that environment variable is empty |
Set the variable (inside the container) or remove the key. Same for Discord, WeCom, Feishu. |
notify.email needs smtp_host, from and at least one to |
Complete the email block. |
notify.email.password_env must name a non-empty environment variable when username is set |
Set the password variable. |
notify.email.api_key_env must name a non-empty environment variable for provider resend |
Set the Resend API key variable. |
blocking.write_token_env must differ from cloudflare.api_token_env |
Keep the two tokens in different variables. |
archive.hourly_retention_days must be >= 30 |
The long baseline needs 28 days. |
warning: no notification channel configured |
Not an error: findings only go to the log. Configure a channel. |
Access and plan¶
the token cannot see this zone/account— the token is not scoped to that zone, or (withworkers) lacks Account → Account Analytics: Read for that account.not available on this plan, degraded: clientAsn, clientASNDescription, firewall events— normal on Free. See Limitations.capability probe failed, assuming full analytics— the probe query failed; FlareHound carries on and retries next round. If later queries fail on missing fields, check the token and plan.- WAF audit "unavailable … lacks Zone → WAF: Read" — add WAF: Read to the read token, or set
waf_audit.disabled.
No messages¶
- Silence is the default. No anomaly, no message — only the daily report is sent every day. Look for
quiet (findings=0, active=false)in the log. window … already evaluated, skipping— each window is evaluated once; a restart or an earlier-oncerun already did it.-dry-runruns do not count: they print instead of sending and leave no trace (no state file write, no alert history), so the real run that follows still evaluates the window.- Delivery failures — failed messages are queued in
data/outbox.jsonand re-sent next round with[delayed]; messages older than 48 hours are dropped with a log line. Check the logged error (HTTP 4xx,wecom errcode …,feishu code …,email: …). - Telegram sends only when both the token variable and
telegram_chat_idare set; a webhook or Telegram variable that is empty silently leaves that channel off. - Email —
server does not offer STARTTLS: use"tls": "tls"(port 465) or, for a local relay only,"none". Credentials are never sent overnone.connect: … i/o timeoutusually means the host blocks outbound SMTP — switch to"provider": "resend"(HTTPS).
Numbers look wrong¶
- Higher than the dashboard — expected; run
flarehound calibrate. See Calibration. - Many 504 / 5xx at the edge but visitors are fine — likely cache-operation artifacts; list them under
daily.artifacts. - A collapse "withheld: window still filling" — the re-read after
settle_delaystill grew; the data was not settled yet. Raiseschedule.intraday_offsetif this is frequent. - Too many alerts on a small site — raise
thresholds.min_count; register your own monitors underknown_faces.
Blocking and rule changes¶
environment variable CF_WRITE_TOKEN is empty— blocking and rule commands need the separate write token. In Docker, use theflarehound-adminservice.cannot read DNS records to protect your origin IPs— grant Zone → DNS: Read to the write token, or pass--skip-origin-checkif you are sure.custom-rule quota is full— unblock stale entries, merge rules (see the audit's quota section), or grant Zone → WAF: Edit so the IP Access Rules fallback can be used for IPs and ASNs.--for needs the archive/the execution module needs the archive— setarchive.disabledto false.rule changes have no --yes— by design; confirm interactively.- Expired blocks not lifted — the console must hold the write token (it lifts them every 5 minutes), or
flarehound enforcemust be running (docker compose --profile admin up -d). The blocks page warns when neither is. - A read-back mismatch after a rule change — the error includes
flarehound rules restore <id>; compare with the dashboard first.