juanfont/headscale · error

missing ping ID

Error message

missing ping ID

What it means

Error "missing ping ID" thrown in juanfont/headscale.

Source

Thrown at hscontrol/noise.go:327

	log.Trace().Caller().Str("path", req.URL.String()).Msg("not implemented handler hit")
	http.Error(writer, "Not implemented yet", http.StatusNotImplemented)
}

// PingResponseHandler handles HEAD requests from clients responding to a
// [tailcfg.PingRequest]. The client calls this endpoint to prove connectivity.
// The unguessable ping ID serves as authentication.
func (h *Headscale) PingResponseHandler(
	writer http.ResponseWriter,
	req *http.Request,
) {
	if req.Method != http.MethodHead {
		http.Error(writer, "method not allowed", http.StatusMethodNotAllowed)
		return
	}

	pingID := req.URL.Query().Get("id")
	if pingID == "" {
		http.Error(writer, "missing ping ID", http.StatusBadRequest)
		return
	}

	if h.state.CompletePing(pingID) {
		writer.WriteHeader(http.StatusOK)
	} else {
		http.Error(writer, "unknown or expired ping", http.StatusNotFound)
	}
}

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
}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (missing ping ID); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (missing ping ID); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/noise.go:327 when the library encounters an invalid state.

Common situations: A noise ping request arrived without a ping ID. Ensure the client implements the current Tailscale noise protocol.

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