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

Open a new session with openSession and retry the operation with the fresh id

agent session not found: %s

Error message

agent session not found: %s

What it means

session() looks up an agent session by id in the runtime server's registry and returns this error when no session with that id is registered. Every subsequent RPC method (query execution, fetch, disconnect) resolves through session(), so an unknown/stale/closed id causes this error instead of a nil-pointer panic.

Source

Thrown at agents/drivers/neo4j-go/main.go:297

		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: server, 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()
	err := session.server.disconnect()
	session.mu.Unlock()
	r.releaseRuntime(session.runtimeKey)
	return err

View on GitHub (pinned to c0390bff16)

Solutions

Open a new session with openSession and retry the operation with the fresh id
Treat the error as 'session invalid' and re-run the connect handshake rather than retrying the same id
Check that the id you pass matches the one returned/used at openSession time
If the agent restarted, reconnect and re-establish state before issuing queries

Example fix

// before
page, err := call("fetch", map[string]any{"session_id": cachedID})
// after
page, err := call("fetch", map[string]any{"session_id": cachedID})
if err != nil && strings.Contains(err.Error(), "not found") {
    cachedID = openNewSession()
    page, err = call("fetch", map[string]any{"session_id": cachedID})
}

Defensive patterns

Strategy: try-catch

Validate before calling

// keep a live set of ids known to be open
if !knownSessions[id] {
    id, err = openSessionAndReturnID()
    if err != nil { return err }
}

Type guard

func sessionAlive(id string, known map[string]bool) bool {
    return known[id]
}

Try / catch

sess, err := call("query", map[string]any{"session_id": id})
if err != nil && strings.Contains(err.Error(), "agent session not found") {
    id, err = reopenSession() // re-handshake and get a fresh id
    if err != nil { return err }
    sess, err = call("query", map[string]any{"session_id": id})
}
return err

Prevention

Reconnect after any agent restart before issuing commands
Never cache session ids across process restarts of the agent
Disconnect once; guard against double-disconnect by tracking state
Validate ids are passed through unchanged from open to use

When it happens

Trigger: Calling any session-scoped method (query, fetchQueryPage, closeSession paths) with an id that was never opened via openSession, or that was already closed/disconnected, or after the agent process restarted losing its registry.

Common situations: Client kept a session handle across an agent restart; a typo or stale id cached in the client; calling fetch on a session that hit shutdown; double-disconnect where the second call looks up a removed id.

Related errors

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