What causes "response Error %d" in go-kratos/kratos?

Reproduce the exact URL from the error context (server + eurekaPath + operation path) with curl and inspect the Eureka response body for the real cause

go-kratos/kratos · error

response Error %d

Error message

response Error %d

What it means

Returned by the Kratos Eureka registry client when the Eureka server answers an HTTP request with status >= 400 (http.StatusBadRequest). Note this error path is NOT retried: request() returns retry=false, so do() fails immediately even though maxRetry is configured; only transport-level failures are retried. The value is the raw HTTP status code with no response body details.

Source

Thrown at contrib/registry/eureka/client.go:348

	}
	defer func() {
		_, _ = io.Copy(io.Discard, resp.Body)
		_ = resp.Body.Close()
	}()

	if output != nil && resp.StatusCode/100 == 2 {
		data, err := io.ReadAll(resp.Body)
		if err != nil {
			return false, err
		}
		err = json.Unmarshal(data, output)
		if err != nil {
			return false, err
		}
	}

	if resp.StatusCode >= http.StatusBadRequest {
		return false, fmt.Errorf("response Error %d", resp.StatusCode)
	}

	return false, nil
}

func (e *Client) do(ctx context.Context, method string, params []string, input io.Reader, output any) error {
	for i := 0; i < e.maxRetry; i++ {
		retry, err := e.request(ctx, method, params, input, output, i)
		if retry {
			continue
		}
		if err != nil {
			return err
		}
		return nil
	}
	return fmt.Errorf("retry after %d times", e.maxRetry)
}

View on GitHub (pinned to 668db92c2c)

Solutions

Reproduce the exact URL from the error context (server + eurekaPath + operation path) with curl and inspect the Eureka response body for the real cause
Verify the eureka server URL and eurekaPath configuration (commonly /eureka) match your server, including any context path or reverse-proxy prefix
For 404 on instance operations, ensure Register completed before heartbeat/deregister, and that instanceID matches what Eureka assigned
For 401/403, configure the credentials/auth on the eureka client if the server requires them
For 5xx, check Eureka server health/logs (it may be in self-preservation or out of resources) and rely on caller-level retry since the client will not retry status errors

Example fix

// before: wrong path prefix yields 404 "response Error 404"
client := eureka.NewClient(&eureka.Config{Servers: []string{"http://eureka:8761"}})

// after: include the eureka context path
client := eureka.NewClient(&eureka.Config{Servers: []string{"http://eureka:8761/eureka"}})

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify the eureka base config before first use
func checkEureka(cfg *eureka.Config) error {
	if len(cfg.Servers) == 0 {
		return fmt.Errorf("no eureka servers configured")
	}
	for _, s := range cfg.Servers {
		u, err := url.Parse(s)
		if err != nil || u.Scheme == "" || u.Host == "" {
			return fmt.Errorf("bad eureka server URL %q", s)
		}
	}
	return nil
}

Try / catch

err := client.Register(ctx, ins)
if err != nil {
	var msg string
	if errors.As(err, &msg); strings.HasPrefix(err.Error(), "response Error ") {
		code := strings.TrimSpace(strings.TrimPrefix(err.Error(), "response Error"))
		switch code {
		case "404": // instance/app unknown: register first or ignore
		case "401", "403": // fix credentials, do not retry
		default: // 5xx: server-side, safe to retry with backoff
		}
	}
}

Prevention

Smoke-test one full register/get cycle against Eureka in CI to catch path/auth mistakes
Keep the eurekaPath consistent with the server's context path in all environments
Register before scheduling heartbeats and stop heartbeats before deregistering to avoid 404 races
Remember the client does NOT retry 4xx/5xx - put retry-with-backoff at the call site for transient 5xx

When it happens

Trigger: Any Client.do() operation (Register, Deregister, Heartbeat/heartbeat via applications API, GetApplication, UpdateMetadata) receiving a 4xx/5xx: 404 when querying an app or instance not yet registered, 400 for a malformed JSON body (e.g. non-JSON instance payload), 403 when Eureka has auth enabled but credentials are missing, 500/503 when Eureka is unhealthy or throttling.

Common situations: Heartbeat racing deregistration (404 on instance); eureka server path prefix (eurekaPath) misconfigured so URLs hit a non-existent route (404); sending a plain Go struct instead of proper JSON; Eureka behind a proxy returning 502/503; auth (basic auth) not configured on the eureka client.

Related errors

AI-assisted analysis of go-kratos/kratos@668db92c2c (2026-08-16). Data as JSON: /api/errors/dcb63032a2bffedf. Report an issue: GitHub.