What causes "Cassandra connection runtime is closed" in t8y2/dbx?

Reopen the connection before issuing further RPCs

Cassandra connection runtime is closed

Error message

Cassandra connection runtime is closed

What it means

sessionFor guards access to the connection runtime's gocql sessions. If the runtime has been closed (e.g. after Close was called or connection teardown), any attempt to obtain a session returns this error instead of lazily creating a new one.

Source

Thrown at agents/drivers/cassandra-go/runtime.go:57

	config, err := parseCassandraConfig(cp)
	if err != nil {
		return nil, err
	}
	poolSize := runtimePoolSize()
	return &connectionRuntime{
		config:          config,
		sessions:        map[string]*gocql.Session{},
		permits:         make(chan struct{}, poolSize),
		metadataPermits: make(chan struct{}, runtimeMetadataLimit(poolSize)),
	}, nil
}

func (r *connectionRuntime) sessionFor(keyspace string) (*gocql.Session, error) {
	keyspace = strings.TrimSpace(keyspace)
	r.mu.Lock()
	defer r.mu.Unlock()
	if r.closed {
		return nil, errors.New("Cassandra connection runtime is closed")
	}
	if session := r.sessions[keyspace]; session != nil && !session.Closed() {
		return session, nil
	}
	cluster, err := r.config.clusterConfig(keyspace)
	if err != nil {
		return nil, err
	}
	session, err := cluster.CreateSession()
	if err != nil {
		return nil, err
	}
	r.sessions[keyspace] = session
	return session, nil
}

func (r *connectionRuntime) invalidateMetadataSession() {
	var retiredSession *gocql.Session

View on GitHub (pinned to c0390bff16)

Solutions

Reopen the connection before issuing further RPCs
Stop background workers/metadata refreshers when the runtime is closed
Check runtime liveness (or a closed flag exposed by the client) before calling session-dependent methods
Fix lifecycle ordering so Close happens only after all operations complete (sync.WaitGroup / context cancellation)

Example fix

// before
// rows := rpc("execute_query", opts) // runtime already closed
// after
// if !conn.IsOpen() { conn = reconnect() }
// rows := rpc("execute_query", opts)

Defensive patterns

Strategy: try-catch

Validate before calling

// only issue RPCs while the connection is known open
if (!conn.isOpen()) { conn = await reconnect(); }

Type guard

func (c *Client) runtimeOpen() bool {
  c.mu.Lock(); defer c.mu.Unlock()
  return c.runtime != nil && !c.runtime.closed
}

Try / catch

rows, err := rpcSessionCall(...)
if err != nil && strings.Contains(err.Error(), "connection runtime is closed") {
  conn = reconnect()
  rows, err = rpcSessionCall(...) // single retry after reopen
}

Prevention

Cancel background refreshers before calling Close on the runtime
Serialize shutdown: wait for in-flight ops (WaitGroup) then close
Track connection state client-side and refuse RPCs after close
Reconnect transparently on this error for long-lived processes

When it happens

Trigger: Calling validateConnection, connectionInfo, allKeyspaceMetadata, keyspaceMetadata, querySystemIndexes, or listTriggers after the connectionRuntime was closed via its Close method.

Common situations: Race between a shutdown/close and in-flight or queued queries; background metadata refreshers running after disconnect; clients holding a driver handle past connection close and issuing more RPCs.

Related errors

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