What causes "agent session not found: %s" in t8y2/dbx?

Open the session (openSession) before calling methods on it

agent session not found: %s

Error message

agent session not found: %s

What it means

session(id) looks up the agent session in r.sessions under a read lock and returns this error when no session with that id is registered — i.e. the session was never opened, or was already closed/shutdown.

Source

Thrown at agents/drivers/kingbase-go/main.go:316

	if err := s.connect(cp); err != nil {
		return err
	}
	r.mu.Lock()
	defer r.mu.Unlock()
	if _, exists := r.sessions[id]; exists {
		_ = s.disconnect()
		return fmt.Errorf("agent session already exists: %s", id)
	}
	r.sessions[id] = &agentSession{server: s}
	return nil
}

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

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

View on GitHub (pinned to c0390bff16)

Solutions

Open the session (openSession) before calling methods on it
Verify the id matches the one returned/used at open time
Handle stale references: on this error, re-open the session and retry the operation
Check the runtime hasn't been restarted (which clears all sessions)

Example fix

// before: assumes session exists
res, err := rt.Call(id, "query", args)
// after: reopen on not-found
res, err := rt.Call(id, "query", args)
if err != nil && strings.Contains(err.Error(), "not found") {
    if err := rt.OpenSession(id, cp); err != nil { return err }
    res, err = rt.Call(id, "query", args)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Go: confirm session exists before use
if _, err := rt.Session(id); err != nil {
    if err := rt.OpenSession(id, cp); err != nil {
        return err
    }
}

Try / catch

res, err := rt.Call(id, method, args)
if err != nil && strings.Contains(err.Error(), "not found") {
    if err := rt.OpenSession(id, cp); err != nil { return err }
    res, err = rt.Call(id, method, args)
}

Prevention

Invalidate cached session handles on close/shutdown
Map errors to explicit states client-side (open/closed/unknown)
Re-open and retry once on not-found for transient runtime restarts

When it happens

Trigger: Calling any per-session method ('query', 'disconnect', etc.) with an id that was never opened, was closed via closeSession, or was removed after a 'shutdown' of the runtime.

Common situations: Client retrying commands after the session timed out or was closed; stale id cached by the orchestrator across runtime restarts; typo'd or truncated session id passed in JSON-RPC params.

Related errors

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