chenhg5/cc-connect · error

%s

Error message

%s

What it means

The codex app-server sends a standalone `error` JSON-RPC notification; the adapter unmarshals its `message` field and emits it verbatim as a core.EventError on the session's event stream. Unlike error 160, this text comes directly from codex, so its content varies (e.g. stream errors, auth failures). It is a forwarded upstream error, not one composed by this library.

Source

Thrown at agent/codex/appserver_session.go:1170

			s.completeTurn()
		}

	case "account/rateLimits/updated":
		var notif appServerRateLimitsResponse
		if err := json.Unmarshal(paramsRaw, &notif); err == nil {
			s.storeUsage(mapAppServerRateLimits(notif))
		}

	case "thread/tokenUsage/updated":
		var notif appServerThreadTokenUsageNotification
		if err := json.Unmarshal(paramsRaw, &notif); err == nil {
			s.storeContextUsage(mapAppServerTokenUsage(notif))
		}

	case "error":
		var notif errorNotification
		if err := json.Unmarshal(paramsRaw, &notif); err == nil && strings.TrimSpace(notif.Message) != "" {
			s.emitError(fmt.Errorf("%s", notif.Message))
		}
	}
}

func (s *appServerSession) handleItemStarted(item map[string]any) {
	itemType, _ := item["type"].(string)
	if itemType == "" {
		return
	}

	switch itemType {
	case "agentMessage", "reasoning", "userMessage", "plan", "hookPrompt", "contextCompaction":
		return
	}

	s.flushPendingAsThinking()

	switch itemType {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Read the emitted event's Error text — it is the codex backend's own message and states the actual cause.
2. If it mentions auth, re-run `codex login` or refresh credentials.
3. If it mentions rate limits/quota, wait or reduce request frequency.
4. Check codex CLI and cc-connect versions for protocol compatibility.
5. Retry the turn if the message indicates a transient stream error.

Example fix

// caller side: surface forwarded codex errors to the user
for ev := range sess.Events() {
    if ev.Type == core.EventError {
        slog.Warn("codex reported error", "err", ev.Error)
        // before: silently ignore
        // after: reply with ev.Error text or retry
    }
}

for ev := range sess.Events() {
    if ev.Type == core.EventError {
        switch {
        case strings.Contains(ev.Error.Error(), "auth"):
            relogin()
        case strings.Contains(ev.Error.Error(), "rate limit"):
            backoff()
        default:
            logAndSurface(ev.Error)
        }
    }
}

When it happens

Trigger: A JSON-RPC notification with method `error` and a `message` field is received on the app-server notification channel while a session is live; the message is non-empty after trimming.

Common situations: Model/provider stream failures mid-turn; codex auth token expiring; backend 5xx surfacing as error notifications; network interruption between codex and its model backend; rate limit rejections.

Related errors

• codex app-server turn/start: %w
• turn failed (no details)
• codex app-server resume returned empty thread id
• codex app-server start returned empty thread id
• codex app-server thread id is empty

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