t8y2/dbx · error

Agent session not found: %s

Error message

Agent session not found: %s

What it means

session() looks up an agentSession by id and returns 'Agent session not found: %s' when no session with that id is registered. Every method that operates on an existing session routes through this lookup, so a stale or wrong id fails fast.

Source

Thrown at agents/drivers/etcd2-go/main.go:255

	r.sessions[id] = session
	r.mu.Unlock()

	if _, err := session.state.connect(params); err != nil {
		r.mu.Lock()
		delete(r.sessions, id)
		r.mu.Unlock()
		session.state.close()
		return nil, false, err
	}
	return map[string]bool{"ok": true}, false, 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) any {
	r.mu.Lock()
	session := r.sessions[id]
	delete(r.sessions, id)
	r.mu.Unlock()
	if session != nil {
		session.cancelActive()
		session.mu.Lock()
		session.state.close()
		session.mu.Unlock()
	}
	return map[string]bool{"ok": true}
}

View on GitHub (pinned to c0390bff16)

Solutions

1. Open a new session with openSession before using the id.
2. Confirm the id matches the one returned/stored at open time and the same server instance.
3. Handle this error by re-establishing the session rather than retrying the same call.

Example fix

// before
handle("agent-1", "kv_put", ...) // session never opened
// after
openSession("agent-1", connectParams)
handle("agent-1", "kv_put", ...)

if _, known := knownSessionIDs[id]; !known { return fmt.Errorf("session %s not open; call openSession first", id) }

func sessionExists(server *runtimeServer, id string) bool {
    server.mu.RLock(); defer server.mu.RUnlock()
    return server.sessions[id] != nil
}

if err := call(id, method, params); err != nil && strings.Contains(err.Error(), "session not found") {
    // re-open and replay once
    openSession(id, connectParams)
    return call(id, method, params)
}

When it happens

Trigger: Calling any session-scoped method (closeSession path, RPC handlers, shutdown) with an id that was never opened or that was already closed.

Common situations: Using a session id after the server restarted, double-closing a session, typos in the id, id scoped to a different runtime server instance.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• agent session not found: %s
• Agent session already exists: %s
• Hive Agent session not found: %s
• agent session not found: %s
• agent session not found: {id}

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