Troubleshooting

Use this checklist when LinkPeek behaves unexpectedly. Each section links to targeted fix steps.

Start at the symptom you observe first and follow the branch to the matching remediation checklist.

Authentication errors

• Symptom: Login loop or CSRF warning after submitting credentials.
  • Fix: Confirm the reverse proxy forwards cookies and the LINKPEEK_SESSION_TTL is non-zero.
• Symptom: Brute-force lockouts.
  • Fix: Increase LINKPEEK_RATE_LIMIT_LOGIN or add your office IPs to LINKPEEK_IP_ALLOWLIST.

Tunnel outages

• Symptom: Tunnel hostname missing or stale.
  • Fix: Check /api/tunnel/status and the Cloudflared logs. Restart via the Tunnel monitor.
• Symptom: Cloudflare Access blocks preview bots.
  • Fix: Configure a service token for the bot user agent and whitelist it.

Capture and payload issues

• Symptom: No new capture events.
  • Fix: Validate that the endpoint URL matches the active tunnel hostname. Inspect linkpeek logs for rate-limit messages.
• Symptom: Payload variants download empty files.
  • Fix: Ensure DATA_DIR volume is writable and check disk space on the host.

Retry lab flakiness

• Symptom: Scenarios never complete.
  • Fix: Tail docker compose logs retrylab (if running separately) or inspect the Go server logs for worker panics.

Scanner drift

• Symptom: Scheduler stops running jobs.
  • Fix: Restart the scanner queue via the UI and inspect Postgres for deadlocked jobs.
• Symptom: Diff viewer shows gibberish.
  • Fix: Verify the upstream endpoint returns UTF-8 or set custom headers to request the correct encoding.

Export failures

• Symptom: PDF export returns HTTP 500.
  • Fix: Make sure the container has permission to write to DATA_DIR/pdf. Delete any zero-byte files and retry.
• Symptom: NDJSON export truncated.
  • Fix: Upgrade the browser or use curl with the same session cookie for large exports.

Still stuck? Open a GitHub issue with logs from linkpeek, cloudflared, and postgres containers plus the steps to reproduce.