jaegertracing/jaeger · error

initialize: %w

Error message

initialize: %w

What it means

After dialing, the ACP health check sends an initialize request (acp.AgentMethodInitialize) and expects an InitializeResponse; failure is wrapped as "initialize: <cause>". This proves the agent speaks ACP, not just that the socket opened.

Source

Thrown at cmd/jaeger/internal/extension/jaegerquery/internal/jaegerai/aihealth/acp_check.go:63

		}
		defer adapter.Close()

		conn := acp.NewConnection(noopMethodHandler, adapter, adapter)
		conn.SetLogger(silentACPLogger)

		req := acp.InitializeRequest{
			ProtocolVersion: acp.ProtocolVersionNumber,
			ClientCapabilities: acp.ClientCapabilities{
				Fs:       acp.FileSystemCapabilities{ReadTextFile: false, WriteTextFile: false},
				Terminal: false,
			},
			ClientInfo: &acp.Implementation{
				Name:    "jaeger-ai-check",
				Version: version.Get().GitVersion,
			},
		}
		if _, err := acp.SendRequest[acp.InitializeResponse](conn, ctx, acp.AgentMethodInitialize, req); err != nil {
			return fmt.Errorf("initialize: %w", err)
		}
		return nil
	}
}

View on GitHub (pinned to 806f444784)

Solutions

1. Check the agent's logs for errors handling the initialize method.
2. Verify agent protocol compatibility with the ACP version Jaeger's client (jaeger-ai-check) implements.
3. Increase the health check timeout if the agent is slow to respond (ai.health_check_timeout).
4. Rule out intermediaries (proxies) that interfere with WebSocket frames.

if err := healthCheck(ctx); err != nil {
    if strings.Contains(err.Error(), "initialize: ") {
        // agent reachable but protocol/handshake issue: check agent logs and version compat
        log.Printf("ACP initialize failed: %v", err)
    }
}

When it happens

Trigger: WebSocket connects but the initialize request times out (ctx deadline), the agent returns a request error, or the response cannot be decoded as acp.InitializeResponse.

Common situations: Agent accepts connections but speaks a different/incompatible protocol version; agent is overloaded and slow to answer so the health-check context times out; a proxy strips or corrupts frames.

Related errors

• abnormal value of http status code: %v
• dial: %w

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/1f826623cc40ef22. Report an issue: GitHub.