juanfont/headscale · warning

parsing %s: %w

Error message

parsing %s: %w

What it means

Returned by nodeIDParam when the URL segment is present but types.ParseNodeID rejects it — the value is not a valid positive integer node ID. The wrapped parse error includes the offending value.

Source

Thrown at hscontrol/noise.go:355

func stringParam(req *http.Request, key string) (string, error) {
	param := chi.URLParam(req, key)
	if param == "" {
		return "", fmt.Errorf("%w: %s", ErrMissingURLParameter, key)
	}

	return param, nil
}

func nodeIDParam(req *http.Request, key string) (types.NodeID, error) {
	param := chi.URLParam(req, key)
	if param == "" {
		return 0, fmt.Errorf("%w: %s", ErrMissingURLParameter, key)
	}

	id, err := types.ParseNodeID(param)
	if err != nil {
		return 0, fmt.Errorf("parsing %s: %w", key, err)
	}

	return id, nil
}

// SSHActionHandler handles the /ssh-action endpoint, returning a
// [tailcfg.SSHAction] to the client with the verdict of an SSH access
// request.
func (ns *noiseServer) SSHActionHandler(
	writer http.ResponseWriter,
	req *http.Request,
) {
	srcNodeID, err := nodeIDParam(req, "src_node_id")
	if err != nil {
		httpError(writer, NewHTTPError(
			http.StatusBadRequest,
			"Invalid src_node_id",
			err,

View on GitHub (pinned to 565fd254d0)

Solutions

1. Use the numeric node ID from 'headscale nodes list' or the MapResponse peer list
2. Check the wrapped error for the exact value that failed to parse
3. Fix URL construction so the ID segment is the integer node ID, not a key or name

func isValidNodeID(s string) bool {
    _, err := types.ParseNodeID(s)
    return err == nil
}

id, err := types.ParseNodeID(param)
if err != nil {
    return fmt.Errorf("parsing node id %q: %w", param, err)
}

When it happens

Trigger: Passing a non-numeric node ID segment, e.g. /machine/ssh/action/abc/to/5, or a negative/zero value where a node ID is required.

Common situations: Manually invoking Noise API endpoints for debugging; a client bug that puts a node key or hostname where a numeric node ID belongs; URL templates substituted with the wrong variable.

Related errors

• failed to parse ApiKey: invalid display prefix format
• failed to parse ApiKey: prefix too short
• ErrMissingURLParameter
• MOCKOIDC_CLIENT_SECRET not defined
• MOCKOIDC_PORT not defined

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/3f85c1a093d1a655. Report an issue: GitHub.