chenhg5/cc-connect · warning

session %q referenced by key %q not found in %s

Error message

session %q referenced by key %q not found in %s

What it means

readAgentSessionID parses a session file's index/key file and looks up the active session ID in fd.Sessions. If the key references an ID absent from that file's Sessions map, it reports this error as a non-definite failure; findAgentSessionID keeps scanning other candidate files and only surfaces it (via definiteErr) if nothing better is found.

Source

Thrown at cmd/cc-connect/session_id.go:214

		return "", 0, false, nil // file unreadable, skip
	}
	var fd sessionFileData
	if err := json.Unmarshal(data, &fd); err != nil {
		return "", 0, false, nil // malformed, skip
	}
	activeID, ok := fd.ActiveSession[sessionKey]
	if !ok {
		return "", 0, false, nil // key not in this file
	}
	// Key found in this file — errors from here are definitive.
	// Use the file's modtime as fallback when the session entry is missing or
	// has a zero UpdatedAt, so error-candidate timestamps can still compete
	// with valid candidates from other files.
	fileMod := fileModTime(path)

	sess := fd.Sessions[activeID]
	if sess == nil {
		return "", fileMod, false, fmt.Errorf("session %q referenced by key %q not found in %s", activeID, sessionKey, filepath.Base(path))
	}
	ts := sess.UpdatedAt.UnixNano()
	if ts == 0 {
		ts = fileMod
	}
	if sess.AgentSessionID == "" {
		return "", ts, false, fmt.Errorf("agent session ID not yet available (session may still be starting)")
	}
	return sess.AgentSessionID, ts, true, nil
}

// fileModTime returns the file's modification time as UnixNano, or 0 on error.
func fileModTime(path string) int64 {
	info, err := os.Stat(path)
	if err != nil {
		return 0
	}
	return info.ModTime().UnixNano()

View on GitHub (pinned to 4000b2338a)

Solutions

1. Re-run and confirm the key is correct; check what keys exist in the referenced session file
2. Delete or regenerate the stale key/session file pair so the agent recreates them on next session start
3. Start a new agent session so a fresh, consistent key->session entry is written

Example fix

// before
cc-connect agent-sid --project myproj --key stale-session-id
// after
# start a fresh session, then:
cc-connect agent-sid --project myproj --key <new-session-key>

if out=$(cc-connect agent-sid --project "$P" --key "$K" 2>&1); then
  echo "$out"
else
  echo "lookup failed: $out" >&2; exit 1
fi

When it happens

Trigger: A session key/ID stored in the key file (e.g. <project>.sessions.json or hashed naming) no longer has a corresponding entry in the sessions file — stale key after the session file was rewritten, truncated, or created by a different agent version.

Common situations: Manually edited or partially synced agent data directories, agent crash mid-write leaving key and sessions file inconsistent, running `cc-connect agent-sid` against an old project directory.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• opencode: session list: %w
• cannot read sessions directory %s: %w
• no session found for project %q with key %q
• agent session ID not yet available (session may still be sta
• read sessions dir: %w

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