t8y2/dbx · error · UnsupportedOperationException

getExplainInfo is not supported by this agent

Error message

getExplainInfo is not supported by this agent

What it means

getExplainInfo() (execution-plan retrieval, including DM's explain/autotrace modes) is an optional capability; the interface default throws UnsupportedOperationException. Only agents that can produce execution plans override it, so calling it on a non-supporting agent fails immediately with no plan generated.

Source

Thrown at agents/common/src/main/java/com/dbx/agent/DatabaseAgent.java:215

        );
    }

    default QueryPageResult fetchTableReadPage(String sessionId, int pageSize) {
        return AgentExecutionContext.jdbcExecutor().fetchTableReadPage(sessionId, pageSize);
    }

    default boolean closeTableReadSession(String sessionId) {
        return AgentExecutionContext.jdbcExecutor().closeTableReadSession(sessionId);
    }

    /**
     * Get DM execution plan. Supports two modes:
     *   mode="explain" (default) — direct plan, no execution
     *   mode="autotrace"         — enable MONITOR_SQL_EXEC, execute SQL, then get plan with actual stats
     * @return plan text
     */
    default String getExplainInfo(String sql, String database, String schema, int timeoutSecs, String mode) {
        throw new UnsupportedOperationException("getExplainInfo is not supported by this agent");
    }

    void disconnect();

    Connection getConnection();

    default QueryResult executeTransaction(List<String> statements, String schema) {
        Connection conn = getConnection();
        if (conn == null) {
            throw new IllegalStateException("Not connected");
        }
        return TransactionExecutor.executeUpdateStatements(
            conn,
            statements,
            schema,
            this::setSchemaSQL,
            this::resetSchemaSQL
        );

View on GitHub (pinned to c0390bff16)

Solutions

  1. Feature-detect before calling (instanceof an ExplainCapable interface or capability flag) and disable the plan view when unsupported.
  2. Implement getExplainInfo in the agent using the database's native EXPLAIN/plan facility.
  3. Return a user-facing 'execution plans are not supported for this database type' message instead of the raw exception.

Example fix

// before
String plan = agent.getExplainInfo(sql, db, schema, 30, "explain");
// after
if (!(agent instanceof ExplainCapable)) {
    return "Execution plan not supported for this database type";
}
String plan = agent.getExplainInfo(sql, db, schema, 30, "explain");
Defensive patterns

Strategy: type-guard

Validate before calling

if (!(agent instanceof ExplainCapable)) { throw new UserFacingError("Execution plans are not supported for this database type"); }

Type guard

static boolean supportsExplain(DatabaseAgent a) {
    return a instanceof ExplainCapable;
}

Try / catch

try {
    return agent.getExplainInfo(sql, db, schema, timeout, mode);
} catch (UnsupportedOperationException e) {
    return null; // caller renders 'plan not supported'
}

Prevention

When it happens

Trigger: Calling getExplainInfo(sql, database, schema, timeoutSecs, mode) on an agent that does not override the default method — e.g. requesting an execution plan for a database whose driver has no EXPLAIN/AUTOTRACE support.

Common situations: A 'Show execution plan' button is enabled for every connection type but the underlying agent (non-DM or minimal driver) never implemented plan extraction; feature toggled on for older agent versions that predate getExplainInfo.

Related errors

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