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

Reconnect with the connect method to create a new session before issuing further RPCs.

agent session not found: %s

Error message

agent session not found: %s

What it means

session looks up an existing agent session by id; if no session is registered under that id it returns this error. Any RPC that requires a live session (query, metadata, ddl, disconnect, etc.) fails with it when the session was never opened or has already been closed.

Source

Thrown at agents/drivers/cassandra-go/main.go:275

		return err
	}

	r.mu.Lock()
	defer r.mu.Unlock()
	if _, exists := r.sessions[id]; exists {
		r.releaseRuntime(key)
		return fmt.Errorf("agent session already exists: %s", id)
	}
	r.sessions[id] = &agentSession{server: s, runtimeKey: key}
	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()
	session.server.disconnect()
	session.mu.Unlock()
	r.releaseRuntime(session.runtimeKey)
	return nil

View on GitHub (pinned to c0390bff16)

Solutions

Reconnect with the connect method to create a new session before issuing further RPCs.
Ensure only one owner closes the session; remove double-disconnect paths.
After a server restart, discard cached session ids and re-handshake.
Treat this error as 'reconnect required' in client recovery logic.

Example fix

// before
query(sessionID: oldID) // server restarted; session lost
// after
if sessionGone(err) { id = connect(); query(id) }

Defensive patterns

Strategy: try-catch

Type guard

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

Try / catch

if isSessionNotFound(err) {
    id, err = reconnect() // open a fresh session, then retry the RPC once
    if err == nil { return retryOriginal(id) }
}

Prevention

Cache session ids with a generation counter tied to the server lifetime.
Centralize disconnect so no double-close occurs.
Implement automatic re-handshake on session-not-found before surfacing errors.

When it happens

Trigger: Calling any dispatch method other than connect with a session id that is not present in r.sessions — typically after closeSession/disconnect or before any connect succeeded.

Common situations: Client using a stale session id after a server restart (in-memory sessions are lost); double-disconnect; the session being closed by a concurrent worker while another still uses it; typo'd or truncated session id in a multi-session client.

Related errors

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