chenhg5/cc-connect · error

claudecode: timed out waiting for Claude Code /usage panel:

Error message

claudecode: timed out waiting for Claude Code /usage panel: %w

What it means

Raised by the Claude Code /usage probe loop when the probe context deadline expires before a stable usage screen was captured (and no recognized error screen appeared). It wraps context.DeadlineExceeded; the CLI ran but never rendered a settle-able /usage panel in time.

Source

Thrown at agent/claudecode/claude_usage.go:160

	defer ticker.Stop()

	var (
		state       claudeUsageProbeState
		lastScreen  string
		lastChange  = time.Now()
		usageScreen string
	)

	for {
		select {
		case <-probeCtx.Done():
			if usageScreen != "" {
				return usageScreen, nil
			}
			if screenErr := detectClaudeUsageOutputError(lastScreen, stderr.String()); screenErr != nil {
				return "", screenErr
			}
			return "", fmt.Errorf("claudecode: timed out waiting for Claude Code /usage panel: %w", probeCtx.Err())
		case err := <-readDone:
			if err != nil {
				return "", fmt.Errorf("claudecode: read Claude Code /usage output: %w", err)
			}
		case <-processDone:
			if usageScreen != "" {
				return usageScreen, nil
			}
			if screenErr := detectClaudeUsageOutputError(lastScreen, stderr.String()); screenErr != nil {
				return "", screenErr
			}
			if waitErr != nil {
				return "", fmt.Errorf("claudecode: Claude Code exited before /usage rendered: %w", waitErr)
			}
			return "", fmt.Errorf("claudecode: Claude Code exited before /usage rendered")
		case <-ticker.C:
			screen := normalizeClaudeUsageText(terminal.String())
			if screen != lastScreen {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Retry the /usage command — slow terminals occasionally exceed the probe budget
2. Upgrade Claude Code; older versions render /usage slowly or differently
3. Check system load; a starved pty emulator delays screen stabilization

When it happens

Trigger: Thrown at agent/claudecode/claude_usage.go:160 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

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