When wrong port in config-headscale.url is set, then key validation error is uninformative

[agajdosi]

Description

I've been trying to do the first log in to Headplane and I got the following error whole time:
{"level":"error","timestamp":"2026-07-24T21:09:15.186Z","pid":1,"hostname":"a734448d2bda","component":"auth","msg":"Error while validating API key: [object Object]"}

After some digging I've found that the default port in https://github.com/tale/headplane/blob/main/config.example.yaml is 5000, while the Docker examples on Headscale use 8080.

It would be great to have the error message more informative (e.g. Error connecting to Heascale server).
Also the example could use port 8080, or mention that default example port on Headscale is 8080. (I would be happy to make a PR for this docs change.)

Headplane Version

0.7.0

Headscale Version

0.29.3

[pullfrog]

Plan

The issue is that when headscale.url has the wrong port, the API key validation produces an uninformative [object Object] error in logs and a generic error message to the user.

Root Cause

In app/server/headscale/api/transport.ts:70-82, connection errors (e.g., ECONNREFUSED when the port is wrong) are caught and wrapped as a HeadscaleConnectionError inside a React Router data() throw. In app/routes/auth/login/action.ts:84-107, the catch block only handles HeadscaleAPIError (via isDataWithApiError). Connection errors fall through to the generic catch where %s format specifier produces [object Object] for object values.

Changes

1. app/routes/auth/login/action.ts — Handle connection errors (~L84-L99): Add a branch after the isDataWithApiError check that detects HeadscaleConnectionError (using the existing isConnectionError guard from ~/server/headscale/api/error-client) and returns a user-friendly message like "Unable to connect to the Headscale server — check the headscale.url and ensure Headscale is running."

2. app/routes/auth/login/action.ts — Fix log formatting (~L101): Change the generic %s format specifier to %o (Pino supports this for object serialization) or extract error message, so even unexpected errors produce readable logs.

3. config.example.yaml — Add a comment on the headscale.url field noting that Headscale's Docker examples default to port 8080, clarifying the discrepancy with the example value 5000.

All changes are small, localized, and backward-compatible.

Task list (2/3 completed)

• Analyze issue When wrong port in config-headscale.url is set, then key validation error is uninformative #600 and gather context from codebase
• Produce a structured, actionable plan
• Report plan via pullfrog_report_progress

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[linear-code]

HP-569