TroubleshootingCopy Anchor Link

Start with Northplane's logs. Most problems leave an error there, and HEADPLANE_DEBUG_LOG=true adds more detail. Problems specific to one feature are covered on its page:

• Single sign-on
• Browser SSH

Northplane won't startCopy Anchor Link

Northplane checks its configuration at startup and exits with an error that names the problem:

• "The configuration is missing required fields or has invalid values": the list below it names each field. headscale.url and server.cookie_secret are required, and the cookie secret must be exactly 32 characters.
• "Both … and …_path are set": set a sensitive value or its _path, not both.
• "The secret file specified in … could not be accessed": the file from a _path option doesn't exist or isn't readable by Northplane.
• "Could not resolve environment variable": a ${NAME} in a _path option isn't set.

Signing in does nothingCopy Anchor Link

If signing in lands back on the sign-in page, the browser is probably dropping Northplane's cookie. Match server.cookie_secure to how Northplane is reached: true over HTTPS, false over plain HTTP. Behind a reverse proxy that serves HTTPS, leave it at true.

DNS is missing from the navigationCopy Anchor Link

Northplane can't read Headscale's config file. Check that headscale.config_path is set and points to the file as Northplane sees it, inside its container if it runs in one. See Integrations.

Changes only take effect after restarting HeadscaleCopy Anchor Link

The DNS and sign-in restrictions pages say this when no integration is running. Either none is enabled, or the enabled one failed its startup check. In that case the log says the integration is not available, with the reason just above it. The integration's section lists what it needs.

"Headscale didn't come back after restarting"Copy Anchor Link

The change was saved, but Headscale wasn't healthy again within the time limit. Check Headscale's own logs first, since the saved change may be what stops it from starting. With the proc or Kubernetes integration, also check that something restarts Headscale after it stops: a systemd unit with Restart=always, or the kubelet.

DNS records can't be editedCopy Anchor Link

Northplane only edits records in the file from Headscale's dns.extra_records_path, and needs write access to it. Records listed inline under dns.extra_records are read-only. See DNS records.