juanfont/headscale · error

internal server error

Error message

internal server error

What it means

Error "internal server error" thrown in juanfont/headscale.

Source

Thrown at hscontrol/handlers.go:31

	"github.com/juanfont/headscale/hscontrol/assets"
	"github.com/juanfont/headscale/hscontrol/templates"
	"github.com/juanfont/headscale/hscontrol/types"
	"github.com/rs/zerolog/log"
	"tailscale.com/tailcfg"
)

const (
	reservedResponseHeaderSize = 4
)

// httpError logs an error and sends an HTTP error response with the given.
func httpError(w http.ResponseWriter, err error) {
	if herr, ok := errors.AsType[HTTPError](err); ok {
		http.Error(w, herr.Msg, herr.Code)
		log.Error().Err(herr.Err).Int("code", herr.Code).Msgf("user msg: %s", herr.Msg)
	} else {
		http.Error(w, "internal server error", http.StatusInternalServerError)
		log.Error().Err(err).Int("code", http.StatusInternalServerError).Msg("http internal server error")
	}
}

// httpUserError logs an error and sends a styled HTML error page.
// Use this for browser-facing error paths (OIDC, registration confirm)
// where the user should see a branded page instead of plain text.
// Technical details go to the server log; the HTML page only shows
// an actionable message derived from the HTTP status code.
func httpUserError(w http.ResponseWriter, err error) {
	code := http.StatusInternalServerError

	if herr, ok := errors.AsType[HTTPError](err); ok {
		if herr.Code != 0 {
			code = herr.Code
		}

		log.Error().Err(herr.Err).Int("code", code).Msgf("user msg: %s", herr.Msg)

View on GitHub (pinned to 565fd254d0)

Solutions

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

When it happens

Trigger: Thrown at hscontrol/handlers.go:31 when the library encounters an invalid state.

Common situations: A generic internal server error was returned. Inspect headscale server logs at the time of the request for the underlying error.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

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