{"record":{"id":"0bddb188027c5b7c","repo":"jaegertracing/jaeger","slug":"dial-w","errorCode":null,"errorMessage":"dial: %w","messagePattern":"dial: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/jaeger/internal/extension/jaegerquery/internal/jaegerai/aihealth/acp_check.go","lineNumber":44,"sourceCode":"// level errors are still returned to the caller from acp.SendRequest, so\n// nothing diagnostic is lost.\nvar silentACPLogger = slog.New(slog.NewTextHandler(io.Discard, nil))\n\n// NewACPCheck returns a check function that opens a fresh WebSocket\n// connection to agentURL, performs one ACP `initialize` round-trip, and\n// closes. Any transport-level or protocol-level error counts as unhealthy.\n// Suitable for use as aihealth.Config.Check.\nfunc NewACPCheck(agentURL string, agentHeaders configopaque.MapList, logger *zap.Logger) func(ctx context.Context) error {\n\t// The check only sends `initialize` and immediately closes — the sidecar\n\t// should never send a client-bound call in that window, but if it does we\n\t// refuse it rather than crash.\n\tnoopMethodHandler := func(_ context.Context, method string, _ json.RawMessage) (any, *acp.RequestError) {\n\t\treturn nil, acp.NewMethodNotFound(method)\n\t}\n\treturn func(ctx context.Context) error {\n\t\tadapter, err := jaegerai.DialWsAdapter(ctx, agentURL, agentHeaders, logger)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"dial: %w\", err)\n\t\t}\n\t\tdefer adapter.Close()\n\n\t\tconn := acp.NewConnection(noopMethodHandler, adapter, adapter)\n\t\tconn.SetLogger(silentACPLogger)\n\n\t\treq := acp.InitializeRequest{\n\t\t\tProtocolVersion: acp.ProtocolVersionNumber,\n\t\t\tClientCapabilities: acp.ClientCapabilities{\n\t\t\t\tFs:       acp.FileSystemCapabilities{ReadTextFile: false, WriteTextFile: false},\n\t\t\t\tTerminal: false,\n\t\t\t},\n\t\t\tClientInfo: &acp.Implementation{\n\t\t\t\tName:    \"jaeger-ai-check\",\n\t\t\t\tVersion: version.Get().GitVersion,\n\t\t\t},\n\t\t}\n\t\tif _, err := acp.SendRequest[acp.InitializeResponse](conn, ctx, acp.AgentMethodInitialize, req); err != nil {","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/cmd/jaeger/internal/extension/jaegerquery/internal/jaegerai/aihealth/acp_check.go#L26-L62","documentation":"The ACP health check dials the agent's WebSocket endpoint (via DialWsAdapter) to verify the agent is reachable; if the dial fails the check returns \"dial: <cause>\". It exists so the jaegerquery AI extension can report agent connectivity as unhealthy instead of hanging or erroring obscurely later.","triggerScenarios":"Health check runs and DialWsAdapter cannot establish the WebSocket: agent URL wrong, agent process down, TLS rejection, or the HTTP upgrade handshake returns a non-101 status.","commonSituations":"Agent not yet started when Jaeger boots; wrong port/path in the agent URL; missing agent_headers causing an auth-rejecting 401/403 on the upgrade request; network policy blocking the connection.","solutions":["Verify the agent URL (scheme ws:// or wss://, host, port, path) in the AI extension config.","Confirm the agent process is running and listening on that address (curl the endpoint / check its logs).","If the dial fails with an HTTP error status, check the Jaeger log for 'WebSocket dial failed' with status/body to see auth or routing rejection details.","Add required agent_headers (e.g. Authorization) if the agent requires auth."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"u, err := url.Parse(agentURL)\nif err != nil || (u.Scheme != \"ws\" && u.Scheme != \"wss\") {\n    return fmt.Errorf(\"invalid agent URL: %q\", agentURL)\n}","typeGuard":null,"tryCatchPattern":"err := check(ctx)\nif err != nil && strings.HasPrefix(err.Error(), \"dial: \") {\n    // do not tight-loop; back off and re-check agent availability\n    time.Sleep(backoff)\n    err = check(ctx)\n}","preventionTips":["Start the agent before jaeger-query or rely on the extension's readiness reporting instead of assuming startup order.","Validate ws:// or wss:// scheme, host, port and path in configuration.","Ensure network policies/proxies allow WebSocket upgrades to the agent."],"tags":["websocket","health-check","network"],"backgroundTag":"websocket-dial-failed","analyzedSha":"806f4447841ecdb60519f408b004a599d515f437","analyzedAt":"2026-09-01T02:39:22.140Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}