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

Re-open (or reconnect to) the agent session to obtain a fresh agentSessionID before retrying the call

agent session not found: %s

Error message

agent session not found: %s

What it means

The driver keeps interactive agent sessions in an in-memory map keyed by agentSessionID. When a lookup (getSession) is asked for an ID that is not currently tracked, it returns this error. An empty ID is rejected separately with 'agentSessionId is required', so this error specifically means a well-formed ID that has no live session.

Source

Thrown at agents/drivers/oracle-go/main.go:783

		return err
	}
	return nil
}

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) {
	if agentSessionID == "" {
		return nil, errors.New("agentSessionId is required")
	}
	r.mu.RLock()
	session := r.sessions[agentSessionID]
	r.mu.RUnlock()
	if session == nil {
		return nil, fmt.Errorf("agent session not found: %s", agentSessionID)
	}
	return session, nil
}

func (r *runtimeServer) closeSession(agentSessionID string) error {
	if agentSessionID == "" {
		return errors.New("agentSessionId is required")
	}
	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()
	return session.server.disconnect()

View on GitHub (pinned to c0390bff16)

Solutions

Re-open (or reconnect to) the agent session to obtain a fresh agentSessionID before retrying the call
Verify the agentSessionID being passed is the exact ID returned when the session was created (log it at creation)
Check that the session was not closed concurrently (closeSession/disconnect) by another client or timeout
If the driver restarted, treat all prior session IDs as invalid and rebuild client state

Example fix

// before
session, err := rt.getSession(staleSessionID) // error: agent session not found
// after
if _, err := rt.getSession(sessionID); err != nil {
    sessionID, err = rt.openSession(cfg) // recreate session and use new ID
    if err != nil { return err }
}
session, err := rt.getSession(sessionID)

Defensive patterns

Strategy: validation

Validate before calling

func validSessionID(id string) bool { return strings.TrimSpace(id) != "" }
// also track liveness client-side; re-open on lookup failure

Type guard

func hasSession(rt *runtimeServer, id string) bool { _, err := rt.getSession(id); return err == nil }

Try / catch

session, err := rt.getSession(id)
if err != nil {
    // recreate session and retry once with the new ID
    id, err = rt.openSession(cfg)
    if err != nil { return err }
    session, err = rt.getSession(id)
}

Prevention

Treat session IDs as ephemeral: refetch after any driver restart or disconnect
Log the agentSessionID at creation and compare on every use
Centralize session access behind one client wrapper that auto-reopens on 'not found'
Avoid sharing a session ID across independent clients

When it happens

Trigger: Calling any runtime method that resolves a session (e.g. executing statements within an agent session) with an agentSessionID that was never opened, or that was already closed via closeSession/disconnect, or after a driver process restart which cleared the in-memory map.

Common situations: Client caches a session ID from a previous run and reuses it after reconnecting; two concurrent clients where one closed the shared session; a typo'd or truncated session ID passed through tooling; the driver process was restarted so all sessions were lost.

Related errors

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