amir20/dozzle · error

healthcheck failed with status code

Error message

healthcheck failed with status code %d

What it means

HttpRequest in the healthcheck probes its own /healthcheck endpoint and treats any HTTP status other than 200 as a failure. The server is reachable (http.Get succeeded) but returned an error status (e.g. 500 or 503), signaling the Dozzle process is not healthy. This message is a format string; the actual status code is filled in at runtime.

Solutions

1. Log/inspect the returned status code to identify the cause (4xx vs 5xx)
2. Point the healthcheck URL at an unauthenticated endpoint like /healthz or /ping
3. Fix the path/port if the app returns 404 after reconfiguration
4. If the endpoint is protected, add the required credentials or allowlist the healthcheck path
5. If a redirect is expected, follow redirects or accept 2xx-3xx in your own check

resp, err := http.Get(healthURL)
if err == nil {
    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("pre-check: endpoint returned %d", resp.StatusCode)
    }
}

err := healthcheck.HttpRequest(ctx, url)
if err != nil {
    var he *statusError // or match on the message
    if strings.Contains(err.Error(), "status code 4") {
        // auth/routing problem: fix URL or credentials
    } else if strings.Contains(err.Error(), "status code 5") {
        // server problem: retry with backoff
    }
}

When it happens

Trigger: HttpRequest performs a GET against the configured healthcheck URL and the server returns a non-200 status, e.g. the app is behind auth returning 401, the path moved (301), or the service is failing (500/503).

Common situations: Healthcheck URL points to an endpoint behind an auth proxy (401/302 redirect to login), wrong port or path after a refactor (404), or the container is up but crashing on requests (500).

Related errors

• Failed to save alert
• Preview failed
• cloud search failed
• Failed to save destination
• dispatchers fetch failed

AI-assisted analysis of amir20/dozzle@d9463cbe21 (2026-09-07). Data as JSON: /api/errors/5e7b7a910e33ccda. Report an issue: GitHub.

Appendix: source

Thrown at internal/healthcheck/http.go:38

	url := fmt.Sprintf("%s%s/healthcheck", addr, base)

	if !strings.HasPrefix(url, "http") {
		url = "http://" + url
	}

	log.Info().Str("url", url).Msg("performing healthcheck")
	resp, err := http.Get(url)

	if err != nil {
		return err
	}
	defer resp.Body.Close()

	if resp.StatusCode == 200 {
		return nil
	}

	return fmt.Errorf("healthcheck failed with status code %d", resp.StatusCode)
}

View on GitHub (pinned to d9463cbe21)