{"record":{"id":"099b27c6532ffa43","repo":"cockroachdb/cockroach","slug":"error-while-errormessagecontext-sqlapierrorm","errorCode":null,"errorMessage":"Error while ${errorMessageContext}: ${sqlApiErrorMessage(error?.message)}","messagePattern":"Error while (.+?): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"pkg/ui/workspaces/cluster-ui/src/api/sqlApi.ts","lineNumber":250,"sourceCode":"export function isMaxSizeError(message: string): boolean {\n  return !!message?.includes(\"max result size exceeded\");\n}\n\nexport function isPrivilegeError(code: string): boolean {\n  return code === \"42501\";\n}\n\nexport function formatApiResult<ResultType>(\n  results: ResultType,\n  error: SqlExecutionErrorMessage,\n  errorMessageContext: string,\n  shouldThrowOnQueryError = true,\n): SqlApiResponse<ResultType> {\n  const maxSizeError = isMaxSizeError(error?.message);\n\n  if (error && !maxSizeError) {\n    if (shouldThrowOnQueryError) {\n      throw new Error(\n        `Error while ${errorMessageContext}: ${sqlApiErrorMessage(\n          error?.message,\n        )}`,\n      );\n    } else {\n      // Otherwise, just log.\n      getLogger().warn(\n        `Error while ${errorMessageContext}: ${sqlApiErrorMessage(\n          error?.message,\n        )}`,\n      );\n    }\n  }\n\n  return {\n    maxSizeReached: maxSizeError,\n    results: results,\n  };","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/cockroachdb/cockroach/blob/8812064a015d2faf99d3fc7e15880f94042954b0/pkg/ui/workspaces/cluster-ui/src/api/sqlApi.ts#L232-L268","documentation":"formatApiResult is the shared post-processor for every SQL-API-backed cluster-ui request. When the response carries an error that is not a max-size error and shouldThrowOnQueryError is true (the default), it throws 'Error while <errorMessageContext>: <sqlApiErrorMessage>'. Max-size errors are deliberately exempted so callers can still render truncated results; with shouldThrowOnQueryError=false the same condition degrades to a logger warning.","triggerScenarios":"Any executeSqlApi-based call whose internal query failed: SQL syntax/undefined-column errors from cluster-ui query builders, permission denials, cancelled queries, or version drift where a queried crdb_internal table/column does not exist at the connected cluster's version.","commonSituations":"Console pages (databases, statements, insights, schedules) after a cluster upgrade where internal table schemas shifted; console user roles missing crdb_internal access; a query killed by statement_timeout surfacing as an error response.","solutions":["Parse everything after 'Error while <context>:' — sqlApiErrorMessage carries the underlying SQL error code and message","Copy the exact query the failing page generates and run it in a SQL shell as the console user to reproduce","If partial data is acceptable at your call site, pass shouldThrowOnQueryError=false so the error becomes a warning","After upgrades, confirm the console bundle version matches the cluster version (version skew breaks internal queries)"],"exampleFix":"// before\nreturn formatApiResult(results, error, 'retrieving databases');\n\n// after: log and degrade instead of throwing when the page tolerates partial data\nreturn formatApiResult(results, error, 'retrieving databases', false /* shouldThrowOnQueryError */);","handlingStrategy":"fallback","validationCode":null,"typeGuard":"const isQueryError = (e?: SqlExecutionErrorMessage): e is SqlExecutionErrorMessage =>\n  !!e && !isMaxSizeError(e.message);","tryCatchPattern":"try {\n  return formatApiResult(results, error, errorMessageContext);\n} catch (e) {\n  // fallback: same data, degraded UX\n  getLogger().warn(e instanceof Error ? e.message : String(e));\n  return { results, maxSizeReached: false };\n}","preventionTips":["When a page tolerates partial data, pass shouldThrowOnQueryError=false instead of wrapping in ad-hoc catches","Reuse isMaxSizeError checks so oversized-but-valid results still render","Pin console and cluster versions together during upgrades to avoid internal-query drift"],"tags":["cluster-ui","sql-api","typescript","error-handling"],"backgroundTag":null,"analyzedSha":"8812064a015d2faf99d3fc7e15880f94042954b0","analyzedAt":"2026-08-15T16:34:17.351Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}