chenhg5/cc-connect · error

session file not found for %s

Error message

session file not found for %s

What it means

loadContextUsageFromRollout locates the rollout JSONL file for a session under the resolved CODEX_HOME using findSessionFileInCodexHome. When no file matches the session ID it cannot read context usage and returns this error to refreshContextUsageFromRollout. It means the on-disk transcript for the session is missing.

Source

Thrown at agent/codex/context_usage.go:126

	return &cloned
}

func loadContextUsageFromRollout(extraEnv []string, sessionID, cachedPath string) (*core.ContextUsage, string, error) {
	path := strings.TrimSpace(cachedPath)
	if path != "" {
		usage, err := readContextUsageFromRollout(path)
		if err == nil && usage != nil {
			return usage, path, nil
		}
	}

	codexHome, err := resolveCodexHome(extraEnv)
	if err != nil {
		return nil, "", err
	}
	path = findSessionFileInCodexHome(codexHome, sessionID)
	if path == "" {
		return nil, "", fmt.Errorf("session file not found for %s", sessionID)
	}
	usage, err := readContextUsageFromRollout(path)
	if err != nil {
		return nil, path, err
	}
	if usage == nil {
		return nil, path, fmt.Errorf("context usage not found in rollout")
	}
	return usage, path, nil
}

func resolveCodexHome(extraEnv []string) (string, error) {
	if value := getenvFromList(extraEnv, "CODEX_HOME"); value != "" {
		return strings.TrimSpace(value), nil
	}
	if value := strings.TrimSpace(os.Getenv("CODEX_HOME")); value != "" {
		return value, nil
	}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Confirm CODEX_HOME (explicit env, else ~/.codex) contains sessions/<id> rollout files.
2. Retry after the session has produced at least one turn so the rollout file exists.
3. If polling, treat this as transient and skip until the file appears instead of failing hard.
4. Check the codex CLI version still writes rollouts under the expected directory layout.

Example fix

// before
usage, err := refreshContextUsageFromRollout(sessionID)
if err != nil { return err }
// after
usage, err := refreshContextUsageFromRollout(sessionID)
if err != nil {
    if strings.Contains(err.Error(), "session file not found") {
        return nil, nil // rollout not created yet; retry later
    }
    return nil, err
}

codexHome := os.Getenv("CODEX_HOME")
if codexHome == "" { h, _ := os.UserHomeDir(); codexHome = filepath.Join(h, ".codex") }
if _, err := os.Stat(filepath.Join(codexHome, "sessions")); os.IsNotExist(err) {
    // rollout dir not ready; skip polling this round
}

usage, err := refreshContextUsageFromRollout(sessionID)
if err != nil {
    if strings.Contains(err.Error(), "session file not found") {
        time.Sleep(pollInterval) // rollout may not exist yet
        return retryOnce(sessionID)
    }
    return err
}

When it happens

Trigger: refreshContextUsageFromRollout invoked for a sessionID whose rollout file does not exist under CODEX_HOME — e.g. session started before any rollout was flushed, wrong CODEX_HOME resolved from extraEnv, or the file was deleted/pruned.

Common situations: Context-usage polling racing session startup (rollout not yet created); CODEX_HOME set differently in the session env vs the polling process; codex upgraded and rollout layout changed; user manually cleaned ~/.codex/sessions.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• session file not found: %s
• session file not found for %s
• acp: session/new: %w
• acp: session/new: empty sessionId
• acp: no agent session id

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