What causes "agent session already exists: %s" in t8y2/dbx?

Close the existing session (closeSession/disconnect) before reopening with the same ID.

agent session already exists: %s

Error message

agent session already exists: %s

What it means

runtimeServer.openSession registers a new agent session under an ID under the runtime mutex and rejects the call if a session with that ID already exists, returning 'agent session already exists: %s'. It is a uniqueness guard on session IDs.

Source

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

		id := stringParam(params, "agentSessionId")
		if id == "" {
			id = legacyAgentSessionID
		}
		session, err := r.session(id)
		if err != nil {
			return nil, false, err
		}
		session.mu.Lock()
		defer session.mu.Unlock()
		return session.server.dispatch(method, params)
	}
}

func (r *runtimeServer) openSession(id string, params connectParams) error {
	r.mu.Lock()
	if _, exists := r.sessions[id]; exists {
		r.mu.Unlock()
		return fmt.Errorf("agent session already exists: %s", id)
	}
	if len(r.sessions) >= maxAgentSessions {
		r.mu.Unlock()
		return fmt.Errorf("agent session limit reached: %d", maxAgentSessions)
	}
	r.mu.Unlock()

	server, err := newServer(params)
	if err != nil {
		return err
	}
	if err := server.validateConnection(); err != nil {
		server.disconnect()
		return err
	}

	r.mu.Lock()
	defer r.mu.Unlock()

View on GitHub (pinned to c0390bff16)

Solutions

Close the existing session (closeSession/disconnect) before reopening with the same ID.
Generate a unique session ID (e.g. UUID) per connection instead of reusing one.
Look up and reuse the existing session via session(id) instead of opening a new one.
Restart the agent runtime if a stale session cannot be reclaimed through the API.

Example fix

// before
rt.openSession("agent-1", params) // again after crash
// after
if _, err := rt.session("agent-1"); err != nil {
    rt.openSession("agent-1", params)
}

Defensive patterns

Strategy: try-catch

Validate before calling

func sessionOpen(rt *runtimeServer, id string) bool {
    _, err := rt.session(id)
    return err == nil
}

Try / catch

err := rt.openSession(id, params)
if err != nil && strings.Contains(err.Error(), "agent session already exists") {
    if cerr := rt.closeSession(id); cerr != nil {
        return cerr
    }
    err = rt.openSession(id, params)
}

Prevention

Use unique UUIDs as session IDs per connection.
Always close sessions on client shutdown or error paths.
Check session existence with session(id) before reopening.

When it happens

Trigger: Calling the agent's connect flow twice with the same session ID without closing the first, or two clients racing to register the same ID.

Common situations: Client retry logic reuses a stale session ID after a dropped connection; a crashed client's session was never closed and a restarted client reconnects with the same ID; parallel test runs share a fixed ID.

Related errors

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