What causes "codex app-server usage unavailable" in chenhg5/cc-connect?

Complete at least one turn so usage data is produced, then retry GetUsage

codex app-server usage unavailable

Error message

codex app-server usage unavailable

What it means

GetUsage first refreshes usage from the app-server and falls back to the cached value; if both the fetch and the cache fail it returns this error. It means no token/usage accounting data is available at all for this session.

Source

Thrown at agent/codex/appserver_session.go:929

}

func (s *appServerSession) GetReasoningEffort() string {
	s.runtimeMu.RLock()
	defer s.runtimeMu.RUnlock()
	return strings.TrimSpace(s.effort)
}

func (s *appServerSession) GetUsage(ctx context.Context) (*core.UsageReport, error) {
	if err := s.refreshUsage(ctx); err != nil {
		if cached := s.cachedUsage(); cached != nil {
			return cached, nil
		}
		return nil, err
	}
	if cached := s.cachedUsage(); cached != nil {
		return cached, nil
	}
	return nil, fmt.Errorf("codex app-server usage unavailable")
}

func (s *appServerSession) GetContextUsage() *core.ContextUsage {
	return s.cachedContextUsage()
}

func (s *appServerSession) Alive() bool {
	return s.alive.Load()
}

func (s *appServerSession) Close() error {
	s.alive.Store(false)
	s.cancel()

	s.procMu.Lock()
	if s.stdin != nil {
		_ = s.stdin.Close()
		s.stdin = nil

View on GitHub (pinned to 4000b2338a)

Solutions

Complete at least one turn so usage data is produced, then retry GetUsage
Verify the codex binary/account supports usage reporting and is properly authenticated
Retry GetUsage later once the cache is populated after a successful fetch
Handle nil usage gracefully in the caller instead of failing the command

Example fix

// before
usage, err := sess.GetUsage(ctx)
if err != nil { return err }
// after
usage, err := sess.GetUsage(ctx)
if err != nil {
    slog.Warn("usage not available yet", "err", err)
    return nil // render placeholder UI instead of failing
}

Defensive patterns

Strategy: fallback

Validate before calling

// no pre-call validation possible; gate on a completed turn
if sess.TurnCount() == 0 {
    // usage not yet available
}

Try / catch

usage, err := sess.GetUsage(ctx)
if err != nil {
    // show "usage unavailable" placeholder; retry after next turn
    usage = nil
}

Prevention

Only request usage after at least one completed turn
Retry with backoff — the cache fills after the first successful fetch
Verify the codex account/auth supports usage reporting
Return cached=nil gracefully in UI code instead of erroring the command

When it happens

Trigger: Calling GetUsage when the usage fetch request fails (or returns empty) and s.cachedUsage() returns nil because no successful usage response has ever been received this session.

Common situations: Fresh session that has not completed a turn yet (no usage data recorded); codex binary that doesn't emit usage/account info; usage request timed out right after startup; auth issues preventing the account/usage lookup.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

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