Troubleshooting

Start with the logs. They usually name the problem.

Component	Where
Server	docker compose logs pf-central (JSON by default; set PFCENTRAL_LOG_JSON=false for text)
Agent	/var/log/nats_agent.log on the firewall
Agent status	Services → pfCentral → Status, or /var/run/nats-agent.status.json
Agent service	service nats_agent status

Quick map

 Device never appears / stays "awaiting enrollment"  → Enrollment (HTTP, port 443/2808)
 Status tab says Enrolled, pfCentral says offline     → Connection (NATS, port 24222)
 Online, but a page shows an error or times out       → Requests
 Nobody can sign in                                   → Web UI
 Server will not start                                → Server start-up

Web UI

Sign-in page reloads

You enter the right password and land back on the sign-in page with no error.

• Plain HTTP: the session cookie is Secure by default and the browser drops it. Use HTTPS, or set PFCENTRAL_COOKIE_SECURE=false on a lab install.
• Wrong origin: the address in the browser must be listed in PFCENTRAL_TRUSTED_ORIGINS, exactly, with scheme and port. For example https://pf.example.com.

“Forbidden” when submitting a form

The request’s origin is not in PFCENTRAL_TRUSTED_ORIGINS. Add your public URL. Behind a proxy, make sure it passes the original Host header.

Pages look frozen; live data does not update

A proxy is buffering the server-sent event streams or closing them early. Turn off buffering and raise the read timeout; see HTTPS for the web UI.

HTTP 429 Too Many Requests

The server-wide rate limit (600 requests per minute by default) is used up. Busy scripts and many open live pages share it. Raise PFCENTRAL_RATELIMIT_GLOBAL_RPM.

“Not permitted”

Your role does not allow the action. See Roles and permissions. The refusal is in the audit log with the reason.

Lost the setup link, or no owner can sign in

Run pf-central admin setup token on the server (docker compose exec pf-central pf-central admin setup token). It prints a new link that creates an owner.

Enrollment

The agent trades its token for credentials at POST /enroll. Errors appear in /var/log/nats_agent.log.

Log or status	Cause	Fix
401 bootstrap token invalid or expired	Token used, expired (UI tokens last 1 hour) or mistyped	Make a new token
500 enrollment failed	A UUID-bound token was used by a firewall with a different device ID	Check kenv smbios.system.uuid matches the UUID you entered, or use an unbound CLI token
Connection refused or timeout to the enroll URL	The firewall cannot reach the web port	Test with fetch -o /dev/null https://pf.example.com/login
Certificate error on the enroll URL	The proxy’s certificate is not trusted by the firewall	Use a public certificate, or install your CA in System → Cert. Manager
Already enrolled when adding in the UI	This UUID has credentials already	Use an unbound token to re-enroll, or delete the device first

Connection (enrolled but offline)

The agent has credentials but cannot stay connected to NATS.

1. Port. From the firewall: nc -vz pf.example.com 24222. If it fails, check the server host’s firewall, the published port, and any upstream rules.
2. Scheme. nats:// against a server with TLS on, or tls:// against one without, fails. They must match.
3. CA. With tls://, /usr/local/etc/nats-agent/ca.crt must be the server’s current CA. Click Save in Services → pfCentral → Settings to download it again. If the server’s state/nats/tls/ was deleted, the CA changed.
4. Name. The host in the NATS URL must be in PFCENTRAL_NATS_TLS_HOSTS. Test: openssl s_client -connect pf.example.com:24222 -CAfile /usr/local/etc/nats-agent/ca.crt -verify_hostname pf.example.com.
5. Authorization. authorization violation in the agent log means the server refused the login: the device was deleted, or the connect-secret no longer matches (for example after a pepper change without the old value). Re-enroll the firewall.

The agent retries every few seconds forever, so it reconnects on its own once the cause is fixed.

Devices flap between online and offline

The link loses heartbeats for more than 15 seconds at a time. Check packet loss on the path. On very poor links, raise PFCENTRAL_NATS_REGISTRY_MAX_MISSED_SWEEPS (default 3). See Online, offline and telemetry.

Requests

Error	Cause	Fix
Timeout	The firewall did not answer within 5 seconds: offline, overloaded, or a slow pfSense operation	Check the device is online and retry
Config locked	Someone is saving in the pfSense GUI at the same moment	Retry in a few seconds
Apply failed	pfSense rejected the configuration when reloading the service	Read the message; check the same area in the pfSense GUI
Stale data in a list	Lists may come from a short-lived cache; a background refresh starts after 30 seconds	Reload the page after a few seconds

Server start-up

Log	Cause	Fix
desynchronised state	The database and the state volume do not match: one was lost, replaced or restored alone	Restore both from the same backup. See Back up and restore.
Database connection errors	Wrong PFCENTRAL_DATABASE_URL, or PostgreSQL not ready	Check the DSN; in Compose use depends_on with a health check
Email settings errors	Email is on but a key, From address or credential is missing	Complete the settings or set PFCENTRAL_EMAIL_ENABLED=false
External NATS errors	Missing creds files, creds from different accounts, or an expired identity	See Bring your own NATS

Ask for help

When you open an issue, include the server version (avatar menu), the agent version (Status tab), the relevant log lines with secrets removed, and which of the sections above you tried.