t8y2/dbx · error · errAgentSessionNotFound

%w: %s

Error message

%w: %s

What it means

runtimeServer.session looks up an agent session by ID and wraps errAgentSessionNotFound ('agent session not found') with the requested ID when no entry exists. It is the lookup primitive used by nearly every RPC that takes an agentSessionId, so any unknown or expired ID surfaces as this error.

Source

Thrown at agents/drivers/xugu/main.go:955

	r.connectMu.Unlock()
	if !controlAttached {
		r.releaseControl(session.controlKey)
		session.controlKey = ""
	}
	return err
}

func (r *runtimeServer) replaceSession(agentSessionID string, params connectParams) error {
	_ = r.closeSession(agentSessionID)
	return r.openSession(agentSessionID, params)
}

func (r *runtimeServer) session(agentSessionID string) (*agentSession, error) {
	r.mu.RLock()
	session := r.sessions[agentSessionID]
	r.mu.RUnlock()
	if session == nil {
		return nil, fmt.Errorf("%w: %s", errAgentSessionNotFound, agentSessionID)
	}
	return session, nil
}

func (r *runtimeServer) closeSession(agentSessionID string) error {
	r.mu.Lock()
	session := r.sessions[agentSessionID]
	delete(r.sessions, agentSessionID)
	r.mu.Unlock()
	if session == nil {
		return nil
	}
	session.mu.Lock()
	defer session.mu.Unlock()
	err := session.server.disconnect()
	r.releaseControl(session.controlKey)
	return err
}

View on GitHub (pinned to c0390bff16)

Solutions

1. Re-open the session with open_session to obtain a new valid agentSessionId.
2. Check that the agent process has not restarted since the ID was issued.
3. Treat the error as terminal for that ID (sessionDisposition=quarantine in the RPC contract) and rebuild state rather than retrying with the same ID.
4. Verify the ID sent matches the one returned from open_session exactly.

Example fix

// before
run(storedID, q) // agent restarted; ID is dead
// after
if _, err := rt.session(storedID); err != nil {
  storedID = openSession(connStr)
}
run(storedID, q)

// verify ID is non-empty and was issued by open_session
if id == "" || !issuedIDs[id] {
  return fmt.Errorf("refusing RPC with unknown session id %q", id)
}

func isSessionNotFound(err error) bool {
  return err != nil && strings.Contains(err.Error(), "agent session not found")
}

if err := rpc(id); err != nil {
  if isSessionNotFound(err) {
    id = openSession(connStr) // rebuild state; do NOT retry same ID
    rpc(id)
  }
}

When it happens

Trigger: Calling any RPC with an agentSessionId that was never opened, was already closed via close_session/disconnect, or vanished because the agent process restarted (sessions are in-memory).

Common situations: Client caches a session ID across an agent restart; double close_session; agent crash losing all sessions; typo or stale ID restored from a serialized state store.

Related errors

• agent session not found
• scheduler job name is required
• sequence name is required
• synonym name is required
• sql is required

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/f33ad472e63241d4. Report an issue: GitHub.