What causes "%s timed out" in chenhg5/cc-connect?

Check whether the codex app-server process is alive and responsive (`ps aux | grep codex`).

%s timed out

Error message

%s timed out

What it means

Returned by `requestWithTimeout` when, after the JSON-RPC write completes, the total deadline for the request has already elapsed (remaining <= 0), so the adapter abandons the call before waiting for a response. The message is `<method> timed out`, e.g. `thread/start timed out`. It indicates the app-server took longer than `appServerRequestTimeout` even to accept the write.

Source

Thrown at agent/codex/appserver_session.go:1633

		"jsonrpc": "2.0",
		"id":      id,
		"method":  method,
		"params":  params,
	}

	deadline := time.Now().Add(timeout)
	if err := s.writeJSONWithTimeout(method, payload, timeout); err != nil {
		s.pendingMu.Lock()
		delete(s.pending, id)
		s.pendingMu.Unlock()
		return err
	}
	remaining := time.Until(deadline)
	if remaining <= 0 {
		s.pendingMu.Lock()
		delete(s.pending, id)
		s.pendingMu.Unlock()
		return fmt.Errorf("%s timed out", method)
	}

	timer := time.NewTimer(remaining)
	defer timer.Stop()
	ctxDone := s.contextDone()
	select {
	case resp := <-ch:
		if resp.Error != nil {
			return fmt.Errorf("%s", strings.TrimSpace(resp.Error.Message))
		}
		if out != nil {
			if err := json.Unmarshal(resp.Result, out); err != nil {
				return fmt.Errorf("decode %s response: %w", method, err)
			}
		}
		return nil
	case <-ctxDone:
		return s.contextErr()

View on GitHub (pinned to 4000b2338a)

Solutions

Check whether the codex app-server process is alive and responsive (`ps aux | grep codex`).
Restart the codex process / recreate the session — a hung child usually stays hung.
Increase `appServerRequestTimeout` if legitimate operations are slow in your environment.
Check system resources (CPU, load) on the host running codex.
Verify the codex binary version starts correctly standalone before cc-connect launches it.

Example fix

// before: single short timeout on a slow machine
s.request(method, params, out)

// after: use requestWithTimeout with a larger budget
err := s.requestWithTimeout(method, params, out, 60*time.Second)

Defensive patterns

Strategy: retry

Validate before calling

// before calling: ensure the codex process is responsive
if !sess.Alive() {
    return fmt.Errorf("codex session dead; restart before requesting")
}

Try / catch

err := sess.requestWithTimeout(method, params, out, 60*time.Second)
if err != nil && strings.HasSuffix(err.Error(), "timed out") {
    // rebuild session once, then retry
    sess, err = agent.StartSession(ctx, opts)
    if err == nil {
        err = sess.requestWithTimeout(method, params, out, 60*time.Second)
    }
}

Prevention

Size the timeout for cold starts on slow hosts.
Health-check the codex process before requests.
Avoid overloading a single app-server with parallel turns.
Restart hung sessions proactively.

When it happens

Trigger: Calling any request method (thread/start, turn/create, etc.) where `writeJSONWithTimeout` consumed the entire timeout budget (e.g. blocked stdin pipe), leaving `time.Until(deadline)` <= 0 before the select on the response channel begins.

Common situations: Codex app-server process is hung or not reading stdin; slow machine under heavy load; disk/full pipe blocking the write; oversized payload serialization; container CPU throttling.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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