t8y2/dbx · error

Agent session not found: %s

Error message

Agent session not found: %s

What it means

The runtime server looked up the requested session id in r.sessions and found nothing. Every per-session method (connect, get, put, watch, close, ...) is routed through session(id), which validates the id first. It means the session was never opened, was already closed, or the id is misspelled.

Source

Thrown at agents/drivers/etcd-go/main.go:284

	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. Call openSession first (or re-open) with the id before issuing session-scoped methods
2. Check that the session id matches exactly the one returned/used at open time
3. If the server restarted, re-open the session and re-establish connection and watches

Example fix

// before
server.call("get", map[string]any{"id": "agent-1", "key": "foo"}) // closed earlier

// after
if _, err := server.call("get", map[string]any{"id": id}); err != nil && strings.Contains(err.Error(), "not found") {
    server.call("open", map[string]any{"id": id})
    server.call("connect", map[string]any{"id": id})
}

// keep a local registry of ids you successfully opened
func sessionKnown(id string) bool {
    _, ok := openedSessions[id]
    return ok
}

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

resp, err := runtime.Call("get", req)
if isSessionNotFound(err) {
    if _, oerr := runtime.Call("open", map[string]any{"id": id}); oerr != nil { return oerr }
    resp, err = runtime.Call("get", req)
}

When it happens

Trigger: Calling any session-scoped runtime method with an id that is not currently in r.sessions — typically after closeSession/shutdown removed it or before openSession succeeded.

Common situations: Using a session after its close call completed; server restart wiping in-memory sessions while the client keeps the old id; typos in session ids; concurrent close racing with another call on the same id.

Related errors

• Agent session already exists: %s
• ETCD_WATCH_SCOPE_INVALID
• ETCD_WATCH_NOT_FOUND
• lease, ttl, and preserveLease cannot be specified together
• Hive Agent session already exists: %s

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