cockroachdb/cockroach · error · Error

Error while retrieving insights information: ${sqlApiErrorMe

Error message

Error while retrieving insights information: ${sqlApiErrorMessage(result.error.message)}

What it means

Thrown while building transaction insight details: executeInternalSql runs createTxnInsightsQuery (crdb_internal.transaction_insights filtered by execID/start/end); if the response error is present and isMaxSizeError says it is not merely an oversized result, the error is wrapped and thrown. Max-size errors instead set maxSizeReached and continue with empty txnDetails, so partial insight pages still render.

Source

Thrown at pkg/ui/workspaces/cluster-ui/src/api/txnInsightDetailsApi.ts:111

    statementsErr: null,
  };

  let maxSizeReached = false;
  if (!req.excludeTxn) {
    const request = makeInsightsSqlRequest([
      createTxnInsightsQuery({
        execID: req?.txnExecutionID,
        start: req?.start,
        end: req?.end,
      }),
    ]);

    try {
      const result = await executeInternalSql<TxnInsightsResponseRow>(request);
      maxSizeReached = isMaxSizeError(result.error?.message);

      if (result.error && !maxSizeReached) {
        throw new Error(
          `Error while retrieving insights information: ${sqlApiErrorMessage(
            result.error.message,
          )}`,
        );
      }

      const txnDetailsRes = result.execution.txn_results[0];
      if (txnDetailsRes.rows?.length) {
        txnInsightDetails.txnDetails = formatTxnInsightsRow(
          txnDetailsRes.rows[0],
        );
      }
    } catch (e) {
      errors.txnDetailsErr = maybeError(e);
    }
  }

  if (!req.excludeStmts) {

View on GitHub (pinned to 8812064a01)

Solutions

Read the sqlApiErrorMessage suffix for the concrete SQL failure
Run the createTxnInsightsQuery output manually to check columns exist at your cluster version (SHOW COLUMNS FROM crdb_internal.transaction_insights)
Grant the console role access to the required crdb_internal tables or use an admin user
Retry the page once — transient SQL API errors resolve on reload

Defensive patterns

Strategy: try-catch

Validate before calling

// Cheap capability pre-check before loading an insight deep link
const supportsTxnInsights = await clusterVersionAtLeast('23.1');
if (!supportsTxnInsights) {
  return <EmptyState title='Transaction insights require a newer cluster version' />;
}

Type guard

const hasSqlApiError = (
  r: SqlExecutionResponse<unknown>,
): r is SqlExecutionResponse<unknown> & { error: SqlExecutionErrorMessage } =>
  !!r.error && !isMaxSizeError(r.error.message);

Try / catch

try {
  const details = await getTxnInsightDetailsApi(req);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Error while retrieving insights information')) {
    setError('Transaction insights are unavailable: ' + e.message);
  } else {
    throw e;
  }
}

Prevention

Gate insight pages on cluster version capability
Ensure the console role can read crdb_internal.transaction_insights
Remember a missing execID returns empty rows, not this error — only SQL-level failures throw

When it happens

Trigger: Requesting a transaction insight detail page when the txn insights query fails at the SQL level: missing/renamed columns after version skew, permission errors on crdb_internal.transaction_insights, or gateway failures. Note a nonexistent execID does NOT trigger this — it returns zero rows without error.

Common situations: Opening an insight deep link on an older cluster that lacks transaction insights; console user without crdb_internal privileges; transient SQL API unavailability during page load.

Related errors

AI-assisted analysis of cockroachdb/cockroach@8812064a01 (2026-08-15). Data as JSON: /api/errors/6ae74cec7457f4c2. Report an issue: GitHub.