EC
INTERNAL
gRPCERRORCriticalServer-SideHIGH confidence

An internal server error occurred

What this means

Indicates the server encountered an unexpected internal error. This code is reserved for serious, unrecoverable server-side issues.

Why it happens
  1. 1The server experienced a crash or panic while processing the request.
  2. 2A critical server-side invariant was violated.
  3. 3A downstream service that is essential for the operation returned a critical error.
How to reproduce

The server-side RPC handler encounters a condition it cannot handle, such as a corrupt data structure.

trigger — this will error
trigger — this will error
// Server-side: an unexpected and serious error occurs
async myMethod(call, callback) {
  // This should not happen and indicates a bug or data corruption.
  if (isSystemInCorruptState()) {
    callback({
      code: grpc.status.INTERNAL,
      details: "Critical invariant violated."
    });
  }
}

expected output

StatusCode.INTERNAL: An internal server error occurred

Fix 1

Inspect Server Logs for Severe Errors

WHEN Immediately after receiving an INTERNAL error.

Inspect Server Logs for Severe Errors
// Check server logs for panic, segmentation fault, or out-of-memory errors.
// Look for logs indicating a critical failure.
grep "FATAL|PANIC" /var/log/my-service.log

Why this works

INTERNAL errors are usually accompanied by detailed server-side logs that are essential for debugging the underlying bug.

Fix 2

Consider a Limited Retry with Backoff

WHEN If the internal error might be transient (e.g., a server crashing and restarting).

Consider a Limited Retry with Backoff
// Retry cautiously, as the error might be persistent.
try {
  return await client.myMethod(request);
} catch (e) {
  if (e.code === grpc.status.INTERNAL) {
    // Wait and try once more in case it was a server crash.
    await sleep(1000);
    return await client.myMethod(request);
  }
}

Why this works

A limited, delayed retry can sometimes succeed if the error was caused by a server that was in the process of crashing and restarting.

What not to do

✕ Assume it's a transient issue and retry aggressively

INTERNAL errors often point to serious bugs. Aggressive retries can exacerbate the problem or hide the underlying issue.

Sources

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All gRPC errors