Postconditions: what we check

• connect · connection-failure

  error
  WhenCannot connect to any contact point in cluster
  ThrowsNoHostAvailableError with details of failed contact points
  Required handlingCaller MUST handle NoHostAvailableError. Common causes: - All nodes unreachable - Wrong contact points - Authentication failure Check error.innerErrors for details on each contact point. Implement retry with exponential backoff.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• connect · authentication-failure

  error
  WhenInvalid credentials
  ThrowsAuthenticationError
  Required handlingCaller MUST handle authentication errors. DO NOT retry with same credentials. Verify username/password in connection config.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• execute · syntax-error

  error
  WhenInvalid CQL syntax
  ThrowsResponseError with code indicating syntax error
  Required handlingCaller MUST validate CQL syntax before execution. Common error codes: - 0x2000: Syntax error - 0x2200: Invalid query DO NOT retry - fix CQL syntax.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• execute · unavailable

  error
  WhenRequired replicas unavailable for consistency level
  ThrowsResponseError with code 0x1000 (Unavailable)
  Required handlingCaller MUST handle unavailable errors. Not enough replicas available for requested consistency level. May be transient if nodes are recovering. Consider: 1. Retry with exponential backoff 2. Lower consistency level (if acceptable) 3. Check cluster health
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• execute · timeout

  error
  WhenQuery timeout exceeded
  ThrowsOperationTimedOutError
  Required handlingCaller MUST handle timeout errors. Query took longer than configured timeout. May indicate: - Slow query needing optimization - Overloaded cluster - Network issues Consider retry with exponential backoff for transient issues.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• execute · write-timeout

  error
  WhenWrite operation timeout at replica
  ThrowsResponseError with code 0x1100 (Write_timeout)
  Required handlingCaller MUST handle write timeout errors. Write acknowledged by coordinator but timeout waiting for replicas. Data may or may not be written (non-idempotent risk). Implement idempotent retries or check if write succeeded.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• execute · read-timeout

  error
  WhenRead operation timeout at replica
  ThrowsResponseError with code 0x1200 (Read_timeout)
  Required handlingCaller MUST handle read timeout errors. Timeout waiting for replicas to respond. May be transient - implement retry logic.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• execute · overloaded

  error
  WhenCoordinator node is overloaded
  ThrowsResponseError with code 0x1001 (Overloaded)
  Required handlingCaller MUST handle overloaded errors. Coordinator cannot handle more requests. Implement retry with exponential backoff and jitter.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• execute · invalid-query

  error
  WhenKeyspace or table does not exist
  ThrowsResponseError with code 0x2200 (Invalid)
  Required handlingCaller MUST verify schema exists before querying. DO NOT retry - indicates schema mismatch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• batch · batch-failure

  error
  WhenOne or more statements in batch failed
  ThrowsResponseError with details of failure
  Required handlingCaller MUST handle batch errors. Entire batch fails if any statement fails. Check error code to determine failure reason. Note: Cassandra batches are NOT transactions across partitions.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• batch · write-timeout

  error
  WhenBatch write timeout
  ThrowsResponseError with code 0x1100 (Write_timeout)
  Required handlingCaller MUST handle batch write timeouts. Batch may be partially applied (non-atomic across partitions). Implement idempotent retry logic.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• shutdown · shutdown-error

  warning
  WhenError during shutdown (rare)
  ThrowsError with details of shutdown issue
  Required handlingCaller SHOULD handle shutdown errors. Typically safe to ignore, but log for investigation.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• stream · stream-error

  error
  WhenQuery execution fails during streaming
  ThrowsResponseError emitted via 'error' event
  Required handlingCaller MUST listen for 'error' event on stream. Without error listener, unhandled error will crash process. Errors can occur during query execution or while reading rows. Handle NoHostAvailableError, OperationTimedOutError, ResponseError.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• eachRow · row-callback-error

  error
  WhenQuery fails or row processing throws error
  ThrowsError passed to endCallback parameter
  Required handlingCaller MUST check error parameter in endCallback. Errors include: - NoHostAvailableError: Connection failure - OperationTimedOutError: Query timeout - ResponseError: Server-side query error If row callback throws, eachRow stops and calls endCallback with error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• insert · mapper-insert-no-try-catch

  error
  WhenModelMapper.insert() called without try-catch
  ThrowsNoHostAvailableError, OperationTimedOutError, or ResponseError (write_timeout, overloaded, unavailable)
  Required handlingCaller MUST wrap ModelMapper.insert() in try-catch. The Mapper abstracts CQL but still performs async network operations that can fail with the same error types as Client.execute(). Handle NoHostAvailableError (cluster unreachable), OperationTimedOutError (query timeout), and ResponseError (server-side errors).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[7]
• insert · mapper-insert-if-not-exists-not-checked

  warning
  WhenModelMapper.insert() called with docInfo.ifNotExists=true but result.wasApplied() not checked
  ThrowsDoes not throw — silently returns Result with wasApplied()=false when row already exists
  Required handlingWhen insert() is used as a lightweight transaction (ifNotExists=true), callers MUST check result.wasApplied() after the call. An un-applied conditional insert returns successfully without throwing but the row was NOT written. Without the check, the caller silently proceeds assuming the insert succeeded.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[7]
• update · mapper-update-no-try-catch

  error
  WhenModelMapper.update() called without try-catch
  ThrowsNoHostAvailableError, OperationTimedOutError, or ResponseError
  Required handlingCaller MUST wrap ModelMapper.update() in try-catch. The Mapper abstraction hides the async network operation. Handle the same error types as Client.execute().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[7]
• update · mapper-update-if-exists-not-checked

  warning
  WhenModelMapper.update() called with docInfo.ifExists=true but result.wasApplied() not checked
  ThrowsDoes not throw — silently returns Result with wasApplied()=false when row does not exist
  Required handlingWhen update() is a lightweight transaction (ifExists=true or when condition), callers MUST check result.wasApplied(). If the row does not exist or when condition is not met, the update is silently skipped and the caller proceeds assuming it succeeded.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[7]
• remove · mapper-remove-no-try-catch

  error
  WhenModelMapper.remove() called without try-catch
  ThrowsNoHostAvailableError, OperationTimedOutError, or ResponseError
  Required handlingCaller MUST wrap ModelMapper.remove() in try-catch. Cassandra DELETE is idempotent (no error for non-existent rows) but WILL throw on cluster unavailability, timeout, or overload.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• get · mapper-get-null-not-checked

  error
  WhenModelMapper.get() result accessed without null check when row may not exist
  ThrowsTypeError: Cannot read properties of null (does not throw from get itself)
  Required handlingCaller MUST check if the result is null before accessing any properties. ModelMapper.get() returns null when the row does not exist — it does NOT throw. Pattern: const user = await mapper.get({ id }); if (!user) return null;
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• get · mapper-get-no-try-catch

  error
  WhenModelMapper.get() called without try-catch
  ThrowsNoHostAvailableError or OperationTimedOutError on cluster/network failure
  Required handlingCaller MUST wrap ModelMapper.get() in try-catch. Read operations can fail on connection errors or timeouts.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• find · mapper-find-result-not-iterated

  warning
  WhenModelMapper.find() result treated as Array (calling .map, .filter, .length) without .toArray() first
  ThrowsTypeError: result.map is not a function (Result is not an Array)
  Required handlingCaller MUST call result.toArray() to get a standard Array, or use result.forEach() from the Result interface. The Result type returned by find() is an iterable object — not an Array. Array methods like .map(), .filter(), .length are undefined on it.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• find · mapper-find-no-try-catch

  error
  WhenModelMapper.find() called without try-catch
  ThrowsNoHostAvailableError, ResponseError (unavailable, read_timeout), or OperationTimedOutError
  Required handlingCaller MUST wrap ModelMapper.find() in try-catch. Query failures under load (unavailable, read_timeout) are common for result sets that involve multiple replicas.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• executeConcurrent · execute-concurrent-no-try-catch

  error
  Whenconcurrent.executeConcurrent() called without try-catch (default raiseOnFirstError=true)
  ThrowsFirst error encountered — NoHostAvailableError, OperationTimedOutError, or ResponseError
  Required handlingCaller MUST wrap executeConcurrent() in try-catch when using the default raiseOnFirstError=true mode. The Promise rejects on the FIRST query failure, leaving remaining queries unexecuted. Without try-catch, the crash leaves partial write state with no tracking of which queries succeeded.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[8]
• executeConcurrent · execute-concurrent-errors-not-checked

  error
  Whenconcurrent.executeConcurrent() called with raiseOnFirstError=false but ResultSetGroup.errors not checked
  ThrowsDoes not throw — resolves with ResultSetGroup even if all queries fail
  Required handlingWhen using raiseOnFirstError=false, callers MUST check result.errors.length after the Promise resolves. The function accumulates errors silently in result.errors[] up to maxErrors (default 100). If errors are not checked, ALL failed writes are invisible — the bulk job appears to succeed. Pattern: if (result.errors.length > 0) { throw new Error('Batch had failures'); }
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[8]
• batch · mapper-batch-no-try-catch

  error
  Whenmapping.Mapper.batch() called without try-catch
  ThrowsArgumentError (empty items), Error (non-ModelBatchItem entries), NoHostAvailableError, OperationTimedOutError, or ResponseError (write_timeout, unavailable, overloaded)
  Required handlingCaller MUST wrap mapper.batch() in try-catch. The Mapper.batch() Promise rejects on three distinct error families: (1) input-shape errors (empty array or non-ModelBatchItem entries) that throw before any network call, (2) cluster errors (NoHostAvailableError, OperationTimedOutError) from the underlying client.batch() call, (3) server-side errors (ResponseError with codes 0x1100 write_timeout, 0x1000 unavailable, 0x1001 overloaded). As with Client.batch(), a write_timeout means the batch MAY have been partially applied across partitions — implement idempotent retries or a verification read.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[7][5]
• batch · mapper-batch-lwt-not-checked

  warning
  Whenmapping.Mapper.batch() with conditional (LWT) items but result.wasApplied() not checked
  ThrowsDoes not throw — returns Result with wasApplied()=false when the conditional batch was rejected
  Required handlingWhen a Mapper.batch() contains conditional items (ifNotExists, ifExists, or when conditions), the returned Result reflects the LWT outcome. Callers MUST check result.wasApplied() after the Promise resolves. An un-applied conditional batch resolves successfully but NO writes were performed. Without the check, the caller silently proceeds as if the mutation succeeded.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[7]
• getTable · metadata-gettable-no-try-catch

  error
  Whenclient.metadata.getTable() called without try-catch
  ThrowsDriverError ('Metadata has not been initialized') when called before client.connect(); NoHostAvailableError on control-connection loss during schema query
  Required handlingCaller MUST wrap metadata.getTable() in try-catch. Two distinct rejection paths exist: (1) calling getTable() before client.connect() resolves rejects with an uninitialized DriverError — common in startup race conditions where introspection runs before the driver has populated the schema cache, (2) control-connection failures while the schema query is in flight propagate as NoHostAvailableError from the underlying _schemaParser.getTable() call.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• getTable · metadata-gettable-null-not-checked

  error
  Whenclient.metadata.getTable() result accessed without null check when keyspace/table may not exist
  ThrowsTypeError: Cannot read properties of null (does not throw from getTable itself)
  Required handlingCaller MUST check if the result is null before accessing properties. getTable() returns null synchronously (resolved Promise<null>) when the keyspace is unknown to the loaded schema metadata — it does NOT throw. Pattern: const t = await client.metadata.getTable(ks, name); if (!t) return null; Without the check, downstream property access (.columns, .partitionKeys) crashes the caller with a misleading TypeError.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• refreshKeyspaces · metadata-refreshkeyspaces-no-try-catch

  error
  Whenclient.metadata.refreshKeyspaces() called without try-catch
  ThrowsDriverError ('Metadata has not been initialized') when called before client.connect(); NoHostAvailableError or ResponseError when the control connection fails while loading schema
  Required handlingCaller MUST wrap metadata.refreshKeyspaces() in try-catch. Schema refresh is performed over the control connection and can fail when the cluster is reachable for queries but the control host is being replaced (common during rolling restarts). Without a catch, a post-DDL refresh that hits a transient control-connection error crashes the migration job mid-run, leaving subsequent metadata reads stale until the next refresh.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• executeGraph · execute-graph-no-try-catch

  error
  WhenClient.executeGraph() called without try-catch
  ThrowsNoHostAvailableError when no cluster node is reachable; OperationTimedOutError when graph traversal exceeds timeout; ResponseError for Gremlin syntax errors or server-side traversal failures
  Required handlingCaller MUST wrap client.executeGraph() in try-catch. Unlike client.execute(), graph queries use FallthroughRetryPolicy — the driver NEVER automatically retries on read_timeout, unavailable, or request_error. Every transient failure propagates immediately to the caller. This is by design (graph traversals may mutate state and are not assumed idempotent), but it means callers must implement their own retry/backoff logic for transient failures. Handle: NoHostAvailableError (cluster unreachable or graph service down), OperationTimedOutError (traversal took too long — common for full-graph scans), ResponseError (Gremlin syntax error code 0x2000, or traversal step failure).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11][12]
• executeGraph · execute-graph-array-params

  error
  WhenClient.executeGraph() called with Array as parameters argument (common porting mistake from Client.execute() where Arrays are valid)
  ThrowsTypeError: 'Parameters must be a Object instance as an associative array' — thrown synchronously before any network call
  Required handlingCaller MUST pass parameters as a plain Object (associative array), not an Array. executeGraph() rejects Arrays in graph-executor.js send() before any network call: `if (Array.isArray(parameters)) { throw new TypeError('Parameters must be a Object instance...') }` This is a porting bug when migrating from client.execute() (where params can be Array) to client.executeGraph(). The fix: convert `['value']` to `{ paramName: 'value' }`. Reference parameters in Gremlin as named bindings: `g.V().has('id', id)` with `{ id: 'actual-value' }`.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

client.execute(query, params)
  .catch(err => {
    if (err instanceof errors.NoHostAvailableError) {
      // Handle connection failure
    } else if (err instanceof errors.OperationTimedOutError) {
      // Handle timeout
    }
  });

try {
  const result = await client.execute(query, params);
} catch (err) {
  if (err instanceof errors.NoHostAvailableError) {
    // Handle connection failure
  }
}

client.stream(query)
  .on('readable', () => { /* process rows */ })
  .on('error', err => {
    // MUST handle error event
  });

const result = await client.execute(query, params); // CRITICAL BUG
// No try-catch or .catch() - unhandled rejection crashes app

catch (err) {
  console.log('Error'); // No error type checking
  // Can't distinguish transient from permanent errors
  // No retry logic for transient errors
}