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

Open the session with openSession(id, cp) before using it, or verify existence first with session(id) and handle the not-found case.

t8y2/dbx · error

agent session not found: %s

Error message

agent session not found: %s

What it means

session(id) looks up a registered agent session under a read lock; if no session with that id exists it returns this error. It means an operation was attempted against a session id that was never opened or has already been closed.

Source

Thrown at agents/drivers/vastbase-go/main.go:336

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

View on GitHub (pinned to c0390bff16)

Solutions

Open the session with openSession(id, cp) before using it, or verify existence first with session(id) and handle the not-found case.
Check whether closeSession(id) was called earlier in the flow and avoid reuse afterwards.
Use the session object returned at open time rather than re-looking it up by id, where possible.
Log and compare the exact id strings on both sides to catch encoding/whitespace mismatches.

Example fix

// before
sess, err := r.session("agent-1") // never opened -> error
sess.server.doThing()
// after
sess, err := r.session("agent-1")
if err != nil {
    if openErr := r.openSession("agent-1", cp); openErr != nil {
        return openErr
    }
    sess, err = r.session("agent-1")
}
sess.server.doThing()

Defensive patterns

Strategy: try-catch

Try / catch

sess, err := r.session(id)
if err != nil {
    if strings.HasPrefix(err.Error(), "agent session not found") {
        // lazily reopen, or surface a clear session-expired state to the user
        return r.openSession(id, cp)
    }
    return err
}

Prevention

Keep the *agentSession handle from openSession instead of re-looking up by id.
Invalidate cached ids whenever closeSession is called or the server restarts.
Treat not-found as reopen-and-retry in long-lived clients.
Log id values end-to-end to catch encoding/whitespace mismatches.

When it happens

Trigger: Calling session(id) (and any operation on the returned session) with an id that was never passed to openSession; operating on a session after closeSession(id) succeeded; a typo'd or stale id from a previous process lifetime.

Common situations: Clients caching session ids across server restarts; using a session after its close/disconnect; id mismatch from serialization (e.g. trimming, encoding differences) when passing ids around.

Related errors

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