chenhg5/cc-connect · error

codex app-server initialize: %w

Error message

codex app-server initialize: %w

What it means

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.

Source

Thrown at agent/codex/appserver_session.go:316

			"title":   "CC Connect Codex Agent",
			"version": "0.1.0",
		},
		"capabilities": map[string]any{
			"experimentalApi": true,
			"optOutNotificationMethods": []string{
				"command/exec/outputDelta",
				"item/agentMessage/delta",
				"item/plan/delta",
				"item/fileChange/outputDelta",
				"item/reasoning/summaryTextDelta",
				"item/reasoning/textDelta",
			},
		},
	}

	var resp initResponse
	if err := s.request("initialize", params, &resp); err != nil {
		return fmt.Errorf("codex app-server initialize: %w", err)
	}
	if err := s.notify("initialized", nil); err != nil {
		return fmt.Errorf("codex app-server initialized notify: %w", err)
	}
	return nil
}

func (s *appServerSession) ensureThread(resumeID string) error {
	if resumeID != "" && resumeID != core.ContinueSession {
		params := s.threadRequestParams()
		params["threadId"] = resumeID
		params["persistExtendedHistory"] = true

		var resp threadResumeResponse
		if err := s.request("thread/resume", params, &resp); err != nil {
			return err
		}
		if resp.Thread.ID == "" {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Check the app-server stderr output for a startup crash; fix the underlying binary/config issue.
2. Verify codex CLI version matches the protocol the agent expects; upgrade or pin the codex version.
3. Increase the request timeout if the handshake is merely slow.
4. Test the app-server manually (send an initialize JSON-RPC line over stdin) to confirm the expected response shape.
5. If the child died, correlate with 'codex app-server start' success but immediate pipe EOF.

Example fix

// before
if err := s.request("initialize", params, &resp); err != nil {
    return fmt.Errorf("codex app-server initialize: %w", err)
}
// after
// pin a known-good codex version and add diagnostics:
if err := s.request("initialize", params, &resp); err != nil {
    slog.Error("codex initialize failed; check app-server version and stderr", "err", err)
    return fmt.Errorf("codex app-server initialize: %w", err)
}

// Verify the app-server speaks the expected protocol before relying on it
versionOut, err := exec.Command(bin, "--version").Output()
if err != nil || !supportedCodexVersion(string(versionOut)) {
    return fmt.Errorf("unsupported codex CLI version: %s", versionOut)
}

if err := session.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "app-server initialize") {
        slog.Error("codex handshake failed; check app-server stderr and CLI version", "err", err)
        // optionally retry once after a short backoff
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• codex app-server initialized notify: %w
• acp: initialize: %w
• acp: authenticate (%s): %w
• acp: session/new: %w
• invalid permission decision %q

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/9852261884b04ab6. Report an issue: GitHub.