t8y2/dbx · error

agent is not connected

Error message

agent is not connected

What it means

requireDB returns this error when the agent's *sql.DB handle (s.db) is nil — the agent has no live database connection. Every query, explain, and transaction operation funnels through requireDB, so any RPC issued before a successful connect (or after a disconnect/close) fails with this message.

Source

Thrown at agents/drivers/oracle-go/main.go:1497

		return jdbcURLInfo{Kind: "service", Host: match[1], Port: parsePort(match[2]), Database: match[3]}
	}
	if match := oracleJDBCSIDRegexp.FindStringSubmatch(value); len(match) == 4 {
		return jdbcURLInfo{Kind: "sid", Host: match[1], Port: parsePort(match[2]), Database: match[3]}
	}
	if match := oracleJDBCLegacyRegexp.FindStringSubmatch(value); len(match) == 4 {
		return jdbcURLInfo{Kind: "service", Host: match[1], Port: parsePort(match[2]), Database: match[3]}
	}
	return jdbcURLInfo{}
}

func parsePort(value string) int {
	port, _ := strconv.Atoi(value)
	return port
}

func (s *server) requireDB() (*sql.DB, error) {
	if s.db == nil {
		return nil, errors.New("agent is not connected")
	}
	return s.db, nil
}

func (s *server) listDatabases() ([]databaseInfo, error) {
	rows, err := s.queryRows(oracleListDatabasesSQL, nil)
	if err != nil {
		if isOraclePGALimitError(err) {
			return s.currentSchemaDatabase()
		}
		return nil, err
	}
	defer s.closeRows(rows)
	var result []databaseInfo
	for rows.Next() {
		var name string
		if err := rows.Scan(&name); err != nil {
			return nil, err

View on GitHub (pinned to c0390bff16)

Solutions

1. Call the connect RPC with valid DSN/credentials before any other RPC
2. If the agent was restarted, reconnect and re-run initialization
3. Check the connect call's error return — a failed connect leaves s.db nil
4. Add client-side state tracking so queries are queued until the connection is ready

Example fix

// before
rows := await driver.executeQuery("SELECT 1") // errors: agent is not connected
// after
if (!driver.isConnected()) {
  await driver.connect(dsn)
}
rows := await driver.executeQuery("SELECT 1")

if (!driver.isConnected()) {
  await driver.connect(dsn) // or queue/fail the request locally
}

function isConnected(d) {
  return d != null && typeof d.hasManualTransaction === 'function' && d._connected === true
}

When it happens

Trigger: Issuing any RPC (listDatabases, executeQuery, getExplainInfo, executeTransaction, etc.) before calling connect; after an explicit disconnect; after the agent restarted and its connection pool was not re-established.

Common situations: Client startup ordering bug where queries race the connect call; agent restarted by a supervisor while clients keep their old handles; a failed connect silently swallowed and then queries attempted anyway.

Related errors

• not connected
• Kafka Agent is not connected
• Not connected
• ZooKeeper event stream closed before a session was establish
• Not connected

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