juanfont/headscale · error

unknown or expired ping

Error message

unknown or expired ping

What it means

Error "unknown or expired ping" thrown in juanfont/headscale.

Source

Thrown at hscontrol/noise.go:334

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
}

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)
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (unknown or expired ping); 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 (unknown or expired ping); retry the operation after fixing the input, configuration, or environment.

When it happens

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

Common situations: The ping ID is unknown or has expired. Re-initiate the ping handshake; expired entries are pruned from the session cache.

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