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

Use exactly the session ID returned by the connect/handshake call in subsequent requests.

agent session not found: %s

Error message

agent session not found: %s

What it means

runtimeServer.session looks up a registered agent session by ID under a read lock. If nothing is registered under that ID it returns 'agent session not found: %s', meaning the runtime holds no state for the requested session.

Source

Thrown at agents/drivers/iotdb/main.go:279

		return err
	}

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

View on GitHub (pinned to c0390bff16)

Solutions

Use exactly the session ID returned by the connect/handshake call in subsequent requests.
Re-open the session after a runtime restart before issuing per-session calls.
Handle this error by reconnecting — treat it like a closed session, not a fatal bug.
Drop cached session handles on the client after closeSession/disconnect.

Example fix

// before
sess, err := rt.session(id)
// after
sess, err := rt.session(id)
if err != nil && strings.HasPrefix(err.Error(), "agent session not found") {
    if err = rt.openSession(id, params); err != nil { return err }
    sess, err = rt.session(id)
}

Defensive patterns

Strategy: try-catch

Try / catch

sess, err := rt.session(id)
if err != nil && strings.Contains(err.Error(), "agent session not found") {
    // session was lost (restart or closed); re-open and retry once
    if oerr := rt.openSession(id, params); oerr != nil {
        return oerr
    }
    sess, err = rt.session(id)
}

Prevention

Keep the session ID returned by the handshake; never construct it manually.
Invalidate cached handles after closeSession/disconnect.
Expect in-memory sessions to vanish on runtime restart; implement reconnect.
Guard against double-disconnect by tracking closed state client-side.

When it happens

Trigger: Invoking any per-session operation (query, metadata, disconnect, etc.) with an ID that was never opened, or one already removed by closeSession/shutdown.

Common situations: Client reuses a session ID after the agent runtime restarted (in-memory sessions are lost); calling disconnect twice — the second finds nothing; a stale or typo'd ID cached on the client.

Related errors

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