cassandra-driver

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]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]docs.datastax.com/en/developerhttps://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/
2. [2]docs.datastax.com/en/developerhttps://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/
3. [3]docs.datastax.com/en/developerhttps://docs.datastax.com/en/developer/nodejs-driver/4.6/features/error-handling/
4. [4]docs.datastax.com/en/cassandra-osshttps://docs.datastax.com/en/cassandra-oss/3.x/cassandra/dml/dmlAboutDataConsistency.html
5. [5]docs.datastax.com/en/developerhttps://docs.datastax.com/en/developer/nodejs-driver/4.6/features/batch/
6. [6]docs.datastax.com/en/developerhttps://docs.datastax.com/en/developer/nodejs-driver/4.6/features/queries/
7. [7]docs.datastax.com/en/developerhttps://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/
8. [8]docs.datastax.com/en/developerhttps://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.concurrent/