agent session ID not yet available (session may still be sta

Error message

agent session ID not yet available (session may still be starting)

What it means

readAgentSessionID found the session entry but its AgentSessionID field is empty, meaning the session file exists but the agent has not yet written the real session ID (the session may still be starting). It returns this non-definite error with the session timestamp so findAgentSessionID can prefer other candidates; it surfaces only when no better match exists.

Source

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

	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()
}

func printAgentSIDUsage() {
	fmt.Println(`Usage: cc-connect agent-sid [options]

Print the agent session ID (e.g. Claude Code, Codex, Gemini CLI) for the
current session. This is the ID used for --resume.

View on GitHub (pinned to 4000b2338a)

Solutions

Retry after a short delay (e.g. sleep 1-2s or poll with retries) until the session ID appears
Check the agent process actually started and is running (ps / logs)
If the session is dead, remove the stale entry and start a new session

Example fix

// before
cc-connect agent start ... && cc-connect agent-sid --project $P --key $K
// after
cc-connect agent start ...
for i in $(seq 1 10); do cc-connect agent-sid --project $P --key $K && break; sleep 1; done

Defensive patterns

Strategy: retry

Try / catch

for i in 1 2 3 4 5; do
  sid=$(cc-connect agent-sid --project "$P" --key "$K") && break
  sleep 1
done

Prevention

Insert a startup delay between launching an agent session and querying its ID
Poll instead of querying once in scripts
Check agent logs if the ID never appears

When it happens

Trigger: Running `cc-connect agent-sid` immediately after spawning an agent session, before the agent process has flushed its session ID to the session file.

Common situations: Scripting that starts a Claude Code/Codex session and queries agent-sid in the same second; agent crashed during startup before writing the ID.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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