Menu
Install it
Browse documentation

Pharos / Docs / v1.0.1

Troubleshooting

Updated 2026-10-22 · Pharos 1.0.1

Checks are not running

  1. Prove the runner works: php artisan pharos:check --force. If that works but nothing happens on its own, the scheduler is the problem.
  2. Prove the scheduler fires: php artisan schedule:run, then check the cron line uses an absolute path and the right PHP binary. On Docker, docker compose ps; the scheduler must be up.
  3. Check the component is enabled. Disabled components are skipped entirely.
  4. If every HTTP check says No response, your host almost certainly has allow_url_fopen off or blocks outbound HTTP.
  5. Look in the log of today, storage/logs/laravel-YYYY-MM-DD.log. Pharos writes one file per day and keeps 14 days. The shipped log level is warning. An installation from before 1.0 may still have an old laravel.log next to them; it is no longer written to.
  6. No cron on the host at all? See Web cron.

A component is stuck down

  1. Run php artisan pharos:check --force and read the message beside it.
  2. For heartbeats, call the URL by hand. A 404 means the token is wrong; a 200 means Pharos is fine and your cron is not calling it.
  3. Check nothing else owns it. A workflow that also sets this component will fight the built-in check every minute, so pick one owner.

A DNS or keyword check fails while the site works

  1. Read the message with php artisan pharos:check --force. Expected text is missing, Expected DNS record is missing and DNS lookup failed each point at a different cause.
  2. Expected text is compared exactly, capitals included, and is not looked for behind a redirect. Check the address serves the page itself and that the response is smaller than 1 MiB.
  3. For DNS, compare with what the server itself resolves. An MX value is the priority, a space and the hostname. A TXT value must match the whole record.

A component sits on Degraded performance

  1. Open the component and read the date after TLS certificate expires. With 3 days or less left, Pharos sets the component to Degraded performance. Renew the certificate and the next healthy run sets the component back.
  2. If the check has probe locations, open Services → Probe locations. A line with missing or stale means too few locations reported in time to decide.
  3. On the remote installation, run php artisan pharos:probe-remote by hand. It tells you when the hub address or the credential is refused. Check there that the cron line runs and that the hub address starts with https://.

The admin looks stale

Admin pages already send no-store, so the browser cannot serve you a screen the server never rendered. If it persists, something in front of Pharos is caching, so exclude /admin/* from it. After editing .env, run php artisan optimize:clear.

Mail is not sending

  1. Open Settings → Central mail and press Send test. The result tells you whether the connection works before any subscriber is involved.
  2. What is saved there wins; anything left blank falls back to the MAIL_* lines in .env. The screen shows the effective sender and host it will use.
  3. Subscriber mail is sent from the cron line, so confirm the scheduler is firing (see above); a paused scheduler means no confirmation and no incident mail.
  4. Nothing arrives but the test passes? Check the address is confirmed under Subscribers; an unconfirmed address is never mailed.
  5. One subscriber misses an incident that others got? That address may follow only some services. A subscriber who chose services is not mailed about the others. See Service subscriptions.

Signing in

  • "That code has already been used. Wait for the next one." A two factor code works once. Wait for the app to show a new code and enter that.
  • The passkey button is greyed out. You are on plain HTTP, or the browser has no passkey support. Passkeys need an HTTPS hostname, see Passkeys.
  • "Passkey sign in failed" on an address that is an IP, or after the hostname changed. A passkey only works on the hostname it was made on, and never on an IP address. Sign in with your password.
  • Adding a passkey refuses your password. It wants the password of the Pharos account, not the one of your single sign on provider.

Web cron and remote backups

  • The web cron call answers 404. The switch Enable web scheduler is off.
  • It answers 401. The header is missing or the token differs from PHAROS_WEB_CRON_TOKEN. A token in the address is not read.
  • A remote backup fails. The screen shows one short line on purpose. Check the credentials, and for SFTP the fingerprint. A storage server with a private address needs Allow this destination on a private network.
  • The PDF report does not download. Check that PHP's dom extension is loaded.

Written against the shipping source. If something here does not match what you see, the source is right and this page is wrong. Please say so.