{"record":{"id":"9852261884b04ab6","repo":"chenhg5/cc-connect","slug":"codex-app-server-initialize-w","errorCode":null,"errorMessage":"codex app-server initialize: %w","messagePattern":"codex app-server initialize: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent/codex/appserver_session.go","lineNumber":316,"sourceCode":"\t\t\t\"title\":   \"CC Connect Codex Agent\",\n\t\t\t\"version\": \"0.1.0\",\n\t\t},\n\t\t\"capabilities\": map[string]any{\n\t\t\t\"experimentalApi\": true,\n\t\t\t\"optOutNotificationMethods\": []string{\n\t\t\t\t\"command/exec/outputDelta\",\n\t\t\t\t\"item/agentMessage/delta\",\n\t\t\t\t\"item/plan/delta\",\n\t\t\t\t\"item/fileChange/outputDelta\",\n\t\t\t\t\"item/reasoning/summaryTextDelta\",\n\t\t\t\t\"item/reasoning/textDelta\",\n\t\t\t},\n\t\t},\n\t}\n\n\tvar resp initResponse\n\tif err := s.request(\"initialize\", params, &resp); err != nil {\n\t\treturn fmt.Errorf(\"codex app-server initialize: %w\", err)\n\t}\n\tif err := s.notify(\"initialized\", nil); err != nil {\n\t\treturn fmt.Errorf(\"codex app-server initialized notify: %w\", err)\n\t}\n\treturn nil\n}\n\nfunc (s *appServerSession) ensureThread(resumeID string) error {\n\tif resumeID != \"\" && resumeID != core.ContinueSession {\n\t\tparams := s.threadRequestParams()\n\t\tparams[\"threadId\"] = resumeID\n\t\tparams[\"persistExtendedHistory\"] = true\n\n\t\tvar resp threadResumeResponse\n\t\tif err := s.request(\"thread/resume\", params, &resp); err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif resp.Thread.ID == \"\" {","sourceCodeStart":298,"sourceCodeEnd":334,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/agent/codex/appserver_session.go#L298-L334","documentation":"This error wraps a failure of the JSON-RPC \"initialize\" request sent to the codex app-server immediately after the process starts. If the app-server does not answer the handshake (crashed, wrong protocol version, hung), the session cannot be established and startup aborts. It bundles transport errors (broken pipe, timeout) and protocol errors from the request() helper.","triggerScenarios":"StartSession on the codex agent where the \"initialize\" JSON-RPC request fails: app-server exits during startup, speaks an incompatible protocol version (missing/renamed initialize params), is slow and the request times out, or the pipe was closed because the process died.","commonSituations":"Codex CLI updated and changed its app-server protocol (params/response shape drift); app-server binary crashes on startup due to bad config/env; request timeout too low on a slow machine; broken pipe because the child died instantly (see stderr logs).","solutions":["Check the app-server stderr output for a startup crash; fix the underlying binary/config issue.","Verify codex CLI version matches the protocol the agent expects; upgrade or pin the codex version.","Increase the request timeout if the handshake is merely slow.","Test the app-server manually (send an initialize JSON-RPC line over stdin) to confirm the expected response shape.","If the child died, correlate with 'codex app-server start' success but immediate pipe EOF."],"exampleFix":"// before\nif err := s.request(\"initialize\", params, &resp); err != nil {\n    return fmt.Errorf(\"codex app-server initialize: %w\", err)\n}\n// after\n// pin a known-good codex version and add diagnostics:\nif err := s.request(\"initialize\", params, &resp); err != nil {\n    slog.Error(\"codex initialize failed; check app-server version and stderr\", \"err\", err)\n    return fmt.Errorf(\"codex app-server initialize: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"// Verify the app-server speaks the expected protocol before relying on it\nversionOut, err := exec.Command(bin, \"--version\").Output()\nif err != nil || !supportedCodexVersion(string(versionOut)) {\n    return fmt.Errorf(\"unsupported codex CLI version: %s\", versionOut)\n}","typeGuard":null,"tryCatchPattern":"if err := session.Start(ctx); err != nil {\n    if strings.Contains(err.Error(), \"app-server initialize\") {\n        slog.Error(\"codex handshake failed; check app-server stderr and CLI version\", \"err\", err)\n        // optionally retry once after a short backoff\n    }\n    return err\n}","preventionTips":["Pin a codex CLI version known to match the client protocol.","Capture app-server stderr to logs for crash diagnosis.","Set a generous handshake timeout for slow machines.","Smoke-test the app-server handshake in CI after CLI upgrades."],"tags":["json-rpc","handshake","ipc","protocol"],"backgroundTag":"handshake-failed","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}