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

Check the session ID in the message exists: call the create/open-session method for that ID before dispatching, and verify the ID string matches exactly what createSession registered.

t8y2/dbx · error

Hive Agent session not found: %s

Error message

Hive Agent session not found: %s

What it means

The runtimeServer's in-memory session registry lookup failed: `session(id)` consulted `runtimeServer.sessions[id]` under a read lock and found no entry, so it cannot return an *agentSession. This agent driver keeps named Hive sessions in a map; any dispatch or test path that addresses a session by ID will hit this when the ID was never opened or has already been closed/removed. It is a lookup-miss error, not a network error — the message interpolates the offending session ID so the caller can see which one was unknown.

Source

Thrown at agents/drivers/argo-go/main.go:274

	defer runtimeServer.mu.Unlock()
	if _, exists := runtimeServer.sessions[id]; exists {
		_ = server.disconnect()
		return fmt.Errorf("Hive Agent session already exists: %s", id)
	}
	if len(runtimeServer.sessions) >= maxAgentSessions {
		_ = server.disconnect()
		return fmt.Errorf("maximum Hive Agent sessions reached (%d)", maxAgentSessions)
	}
	runtimeServer.sessions[id] = &agentSession{server: server}
	return nil
}

func (runtimeServer *runtimeServer) session(id string) (*agentSession, error) {
	runtimeServer.mu.RLock()
	session := runtimeServer.sessions[id]
	runtimeServer.mu.RUnlock()
	if session == nil {
		return nil, fmt.Errorf("Hive Agent session not found: %s", id)
	}
	return session, nil
}

func (runtimeServer *runtimeServer) closeSession(id string) error {
	if id == "" {
		id = legacyAgentSessionID
	}
	runtimeServer.mu.Lock()
	session := runtimeServer.sessions[id]
	delete(runtimeServer.sessions, id)
	runtimeServer.mu.Unlock()
	if session == nil {
		return nil
	}
	session.mu.Lock()
	defer session.mu.Unlock()
	return session.server.disconnect()

View on GitHub (pinned to c0390bff16)

Solutions

Check the session ID in the message exists: call the create/open-session method for that ID before dispatching, and verify the ID string matches exactly what createSession registered.
If the session was closed intentionally, re-open a new session and retry the operation; do not reuse the old ID's handle.
Audit for races where closeSession/closeAllSessions runs concurrently with dispatch on the same ID; serialize shutdown after all in-flight requests complete.
If you rely on the legacy empty-ID session, pass the same ID consistently — session() does not fall back to legacyAgentSessionID the way closeSession does.

Example fix

// before
sess, err := rt.session(sessionID) // "Hive Agent session not found: s1" after restart
run(sess)
// after
if _, ok := rt.peekSession(sessionID); !ok {
    if err := rt.createSession(sessionID, params); err != nil {
        return err
    }
}
sess, err := rt.session(sessionID)

Defensive patterns

Strategy: validation

Validate before calling

func sessionExists(rt *runtimeServer, id string) bool {
    rt.mu.RLock()
    defer rt.mu.RUnlock()
    _, ok := rt.sessions[id]
    return ok
}
// call: if !sessionExists(rt, id) { recreate session before dispatch }

Type guard

func asSession(v any) (*agentSession, bool) {
    s, ok := v.(*agentSession)
    return s, ok && s != nil
}

Try / catch

sess, err := rt.session(id)
if err != nil {
    var nfErr = err
    if strings.Contains(nfErr.Error(), "session not found") {
        // recreate the session, then retry once
        if cerr := rt.createSession(id, params); cerr != nil { return cerr }
        sess, err = rt.session(id)
    }
    if err != nil { return err }
}

Prevention

Track session lifecycle client-side: never dispatch to an ID you have not opened or that you already closed.
Re-create sessions after any driver process restart; the registry is in-memory only.
Serialize close operations against in-flight dispatches on the same session ID.
Use one canonical non-empty session ID everywhere, since only closeSession maps "" to the legacy ID.

When it happens

Trigger: Calling `dispatch` with a method that resolves a session via `runtimeServer.session(id)` when the ID is not in `sessions` — e.g. after `closeSession(id)`/`closeAllSessions()` removed it, before `createSession` was ever called for that ID, or after the driver process restarted losing all in-memory sessions.

Common situations: Client keeps a stale session handle across a driver restart; a race where one caller closes the session while another is still dispatching to it; a typo'd or defaulting-empty session ID that was never registered (closeSession maps "" to legacyAgentSessionID but session() does not); test teardown closing sessions while assertions still reference them.

Related errors

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