{"record":{"id":"6ae74cec7457f4c2","repo":"cockroachdb/cockroach","slug":"error-while-retrieving-insights-information-sql","errorCode":null,"errorMessage":"Error while retrieving insights information: ${sqlApiErrorMessage(result.error.message)}","messagePattern":"Error while retrieving insights information: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"pkg/ui/workspaces/cluster-ui/src/api/txnInsightDetailsApi.ts","lineNumber":111,"sourceCode":"    statementsErr: null,\n  };\n\n  let maxSizeReached = false;\n  if (!req.excludeTxn) {\n    const request = makeInsightsSqlRequest([\n      createTxnInsightsQuery({\n        execID: req?.txnExecutionID,\n        start: req?.start,\n        end: req?.end,\n      }),\n    ]);\n\n    try {\n      const result = await executeInternalSql<TxnInsightsResponseRow>(request);\n      maxSizeReached = isMaxSizeError(result.error?.message);\n\n      if (result.error && !maxSizeReached) {\n        throw new Error(\n          `Error while retrieving insights information: ${sqlApiErrorMessage(\n            result.error.message,\n          )}`,\n        );\n      }\n\n      const txnDetailsRes = result.execution.txn_results[0];\n      if (txnDetailsRes.rows?.length) {\n        txnInsightDetails.txnDetails = formatTxnInsightsRow(\n          txnDetailsRes.rows[0],\n        );\n      }\n    } catch (e) {\n      errors.txnDetailsErr = maybeError(e);\n    }\n  }\n\n  if (!req.excludeStmts) {","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/cockroachdb/cockroach/blob/8812064a015d2faf99d3fc7e15880f94042954b0/pkg/ui/workspaces/cluster-ui/src/api/txnInsightDetailsApi.ts#L93-L129","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Cheap capability pre-check before loading an insight deep link\nconst supportsTxnInsights = await clusterVersionAtLeast('23.1');\nif (!supportsTxnInsights) {\n  return <EmptyState title='Transaction insights require a newer cluster version' />;\n}","typeGuard":"const hasSqlApiError = (\n  r: SqlExecutionResponse<unknown>,\n): r is SqlExecutionResponse<unknown> & { error: SqlExecutionErrorMessage } =>\n  !!r.error && !isMaxSizeError(r.error.message);","tryCatchPattern":"try {\n  const details = await getTxnInsightDetailsApi(req);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Error while retrieving insights information')) {\n    setError('Transaction insights are unavailable: ' + e.message);\n  } else {\n    throw e;\n  }\n}","preventionTips":["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"],"tags":["cluster-ui","sql-api","insights","transactions","typescript"],"backgroundTag":null,"analyzedSha":"8812064a015d2faf99d3fc7e15880f94042954b0","analyzedAt":"2026-08-15T16:34:17.351Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}