cockroachdb/cockroach · error · Error

Error while ${errorMessageContext}: ${sqlApiErrorMessage(err

Error message

Error while ${errorMessageContext}: ${sqlApiErrorMessage(error?.message)}

What it means

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.

Source

Thrown at pkg/ui/workspaces/cluster-ui/src/api/sqlApi.ts:250

export function isMaxSizeError(message: string): boolean {
  return !!message?.includes("max result size exceeded");
}

export function isPrivilegeError(code: string): boolean {
  return code === "42501";
}

export function formatApiResult<ResultType>(
  results: ResultType,
  error: SqlExecutionErrorMessage,
  errorMessageContext: string,
  shouldThrowOnQueryError = true,
): SqlApiResponse<ResultType> {
  const maxSizeError = isMaxSizeError(error?.message);

  if (error && !maxSizeError) {
    if (shouldThrowOnQueryError) {
      throw new Error(
        `Error while ${errorMessageContext}: ${sqlApiErrorMessage(
          error?.message,
        )}`,
      );
    } else {
      // Otherwise, just log.
      getLogger().warn(
        `Error while ${errorMessageContext}: ${sqlApiErrorMessage(
          error?.message,
        )}`,
      );
    }
  }

  return {
    maxSizeReached: maxSizeError,
    results: results,
  };

View on GitHub (pinned to 8812064a01)

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)

Example fix

// before
return formatApiResult(results, error, 'retrieving databases');

// after: log and degrade instead of throwing when the page tolerates partial data
return formatApiResult(results, error, 'retrieving databases', false /* shouldThrowOnQueryError */);

Defensive patterns

Strategy: fallback

Type guard

const isQueryError = (e?: SqlExecutionErrorMessage): e is SqlExecutionErrorMessage =>
  !!e && !isMaxSizeError(e.message);

Try / catch

try {
  return formatApiResult(results, error, errorMessageContext);
} catch (e) {
  // fallback: same data, degraded UX
  getLogger().warn(e instanceof Error ? e.message : String(e));
  return { results, maxSizeReached: false };
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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