Postconditions: what we check

• upload · upload-network-error

  error
  WhenNetwork connection fails or times out
  ThrowsApiError with code ECONNRESET, ETIMEDOUT, or HTTP 408/504
  Required handlingCaller MUST wrap bucket.upload() in try-catch block. Network errors can occur due to internet connectivity issues, DNS failures, or Cloud Storage service downtime. The library automatically retries (default: 3 attempts with exponential backoff), but will throw after max retries exhausted.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• upload · upload-permission-error

  error
  WhenIAM permissions insufficient for bucket write
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Verify service account has storage.objects.create permission on the target bucket. This error is NOT automatically retried.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• upload · upload-bucket-not-found

  error
  WhenBucket does not exist
  ThrowsApiError with HTTP 404 Not Found
  Required handlingCaller MUST handle bucket not found errors. Create bucket first using storage.createBucket() or verify bucket name is correct.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• upload · upload-file-not-found

  error
  WhenLocal file path does not exist
  ThrowsError: ENOENT: no such file or directory
  Required handlingCaller MUST validate local file exists before calling upload(). Check with fs.existsSync() or handle file not found errors gracefully.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• download · download-file-not-found

  error
  WhenFile does not exist in bucket
  ThrowsApiError with HTTP 404 Not Found
  Required handlingCaller MUST handle file not found errors. Check if file exists using file.exists() before downloading, or handle 404 gracefully.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• download · download-permission-error

  error
  WhenIAM permissions insufficient for file read
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Verify service account has storage.objects.get permission. This error is NOT automatically retried.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• download · download-network-error

  error
  WhenNetwork connection fails during download
  ThrowsApiError with code ECONNRESET, ETIMEDOUT
  Required handlingCaller MUST handle network errors. Large file downloads are more susceptible to connection timeouts. The library automatically retries, but will throw after max retries exhausted.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• download · download-corruption-error

  error
  WhenDownloaded file hash does not match expected checksum
  ThrowsError with code CONTENT_DOWNLOAD_MISMATCH
  Required handlingCaller MUST retry download when corruption detected. This error indicates the downloaded content differs from what was stored. Retry the download operation.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• delete · delete-not-found

  error
  WhenFile or bucket does not exist
  ThrowsApiError with HTTP 404 Not Found
  Required handlingCaller SHOULD handle 404 errors gracefully. If idempotent delete is desired, catch 404 and treat as success. Otherwise, throw error to caller.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• delete · delete-permission-error

  error
  WhenIAM permissions insufficient for delete
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Verify service account has storage.objects.delete or storage.buckets.delete permission.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• delete · delete-bucket-not-empty

  error
  WhenAttempting to delete bucket that contains files
  ThrowsApiError with HTTP 409 Conflict
  Required handlingCaller MUST delete all files first using bucket.deleteFiles() before deleting bucket, or handle conflict error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• save · save-permission-error

  error
  WhenIAM permissions insufficient for file write
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Verify service account has storage.objects.create permission on the target bucket.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• save · save-network-error

  error
  WhenNetwork connection fails during write
  ThrowsApiError with code ECONNRESET, ETIMEDOUT
  Required handlingCaller MUST handle network errors. The library automatically retries with exponential backoff, but will throw after max retries exhausted.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• getMetadata · getmetadata-not-found

  error
  WhenFile or bucket does not exist
  ThrowsApiError with HTTP 404 Not Found
  Required handlingCaller MUST handle not found errors. Check if resource exists using exists() method before calling getMetadata(), or handle 404 gracefully.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• getMetadata · getmetadata-permission-error

  error
  WhenIAM permissions insufficient for metadata read
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Verify service account has appropriate read permissions for the resource.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• setMetadata · setmetadata-not-found

  error
  WhenFile or bucket does not exist
  ThrowsApiError with HTTP 404 Not Found
  Required handlingCaller MUST handle not found errors. Verify resource exists before attempting to update metadata.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11]
• setMetadata · setmetadata-permission-error

  error
  WhenIAM permissions insufficient for metadata write
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Verify service account has storage.objects.update or storage.buckets.update permission.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11]
• getFiles · getfiles-permission-error

  error
  WhenIAM permissions insufficient for listing
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Verify service account has storage.objects.list permission on the bucket.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• getFiles · getfiles-network-error

  error
  WhenNetwork connection fails
  ThrowsApiError with network error codes
  Required handlingCaller MUST handle network errors. The library automatically retries, but will throw after max retries exhausted.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• createBucket · createbucket-already-exists

  error
  WhenBucket with same name already exists
  ThrowsApiError with HTTP 409 Conflict
  Required handlingCaller SHOULD handle bucket already exists errors. If idempotent create is desired, catch 409 and retrieve existing bucket.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[13]
• createBucket · createbucket-invalid-name

  error
  WhenBucket name violates naming requirements
  ThrowsApiError with HTTP 400 Bad Request
  Required handlingCaller MUST validate bucket names before creation. Names must be globally unique, lowercase, 3-63 characters, and follow DNS naming conventions.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[14]
• createBucket · createbucket-permission-error

  error
  WhenIAM permissions insufficient for bucket creation
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Verify service account has storage.buckets.create permission in the project.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[13]
• deleteFiles · deletefiles-partial-failure

  error
  WhenSome files fail to delete while others succeed
  ThrowsPartialFailureError containing array of failed operations
  Required handlingCaller MUST handle PartialFailureError separately from ApiError. Inspect error.errors array to determine which files failed and why. Consider retry logic for failed operations.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15]
• deleteFiles · deletefiles-permission-error

  error
  WhenIAM permissions insufficient for batch delete
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Verify service account has storage.objects.delete permission on all matching files.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15]
• getSignedUrl · getsignedurl-invalid-credentials

  error
  WhenService account credentials are invalid or missing
  ThrowsApiError with authentication failure
  Required handlingCaller MUST handle credential errors. Signed URLs require service account with private key. Verify GOOGLE_APPLICATION_CREDENTIALS is set correctly.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• getSignedUrl · getsignedurl-file-not-found

  error
  WhenFile does not exist (for read operations)
  ThrowsApiError with HTTP 404 Not Found
  Required handlingCaller SHOULD handle file not found errors. For read URLs, file must exist. For write URLs, file will be created on upload.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[16]
• copy · copy-source-not-found

  error
  WhenSource file does not exist in the bucket
  ThrowsApiError with HTTP 404 Not Found
  Required handlingCaller MUST handle not found errors. Verify source file exists before copying, or catch 404 and handle gracefully. Common when copying files from user-uploaded content that may have been deleted concurrently.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17][18]
• copy · copy-permission-error

  error
  WhenInsufficient IAM permissions to read source or write to destination
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors. Requires storage.objects.get on source and storage.objects.create on destination bucket. Cross-bucket copies also require the service account to have permissions on the destination project. This error is NOT automatically retried.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17]
• copy · copy-precondition-failed

  warning
  WhenGeneration or metageneration precondition check fails
  ThrowsApiError with HTTP 412 Precondition Failed
  Required handlingCaller MUST handle precondition failures when using ifGenerationMatch or ifMetagenerationMatch options. This error indicates the object was modified between the time the caller last read it and the copy attempt. Retry with updated preconditions or handle as a conflict.
  costlowin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[17]
• move · move-non-atomic-duplicate-risk

  error
  WhenCopy succeeds but delete of source fails, leaving duplicate files
  ThrowsApiError from the delete phase — source file still exists alongside copied destination
  Required handlingCaller MUST handle move() errors by checking whether the destination was successfully created before treating the error as a full failure. If delete fails with 404 (already deleted by another process), treat as success. Consider using moveFileAtomic() for same-bucket moves that require atomicity. The file.move() non-atomicity is explicitly documented: "a composition of File#copy and File#delete... which could leave a duplicate file lingering."
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[19]
• move · move-source-not-found

  error
  WhenSource file does not exist
  ThrowsApiError with HTTP 404 Not Found (from copy phase)
  Required handlingCaller MUST handle not found errors. Verify source file exists before moving. 404 errors occur in the copy phase (source doesn't exist) or delete phase (source was deleted between copy and delete, which is safe to ignore).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[19]
• rename · rename-non-atomic-duplicate-risk

  error
  WhenUnderlying move() operation leaves duplicate files if delete fails
  ThrowsApiError — inherits from move() non-atomic behavior
  Required handlingCaller MUST handle rename() errors the same way as move() errors. If an error is thrown, the file may have been copied to the new name but the original not deleted, resulting in duplicates. Check destination existence before retrying.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[20]
• rename · rename-not-found

  error
  WhenFile does not exist
  ThrowsApiError with HTTP 404 Not Found
  Required handlingCaller MUST handle not found errors. Verify file exists before renaming.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20]
• TransferManager.uploadManyFiles · transfer-upload-many-all-or-nothing

  error
  WhenAny single file upload fails — the entire batch fails with Promise.all rejection
  ThrowsApiError from the first failing upload — other in-flight uploads are NOT cancelled
  Required handlingCaller MUST handle errors as a batch failure. uploadManyFiles() uses Promise.all() internally, so the first file failure throws, but other concurrent uploads continue to their natural completion (they are NOT cancelled). Some files may have been uploaded successfully before the error is surfaced. To identify which files succeeded, check GCS for the uploaded objects after the error. For resilient batch uploads, use individual bucket.upload() calls with your own error tracking, or wrap each upload in a try-catch before using Promise.all.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[21]
• TransferManager.uploadManyFiles · transfer-upload-many-permission-error

  error
  WhenService account lacks write permissions on the bucket
  ThrowsApiError with HTTP 403 Forbidden from the first file that encounters the permission error
  Required handlingCaller MUST handle permission errors. Verify service account has storage.objects.create permission before starting a batch upload. Permission errors will typically affect ALL files in the batch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21]
• TransferManager.downloadManyFiles · transfer-download-many-all-or-nothing

  error
  WhenAny single file download fails — the entire batch fails
  ThrowsApiError from the first failing download
  Required handlingCaller MUST handle errors as a batch failure. downloadManyFiles() uses Promise.all() — the first file failure throws and surfaces as the batch error, but other concurrent downloads continue running. Some files may be written to disk while others are missing. Check local filesystem for which files were successfully downloaded before retrying.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[21]
• TransferManager.downloadManyFiles · transfer-download-many-file-not-found

  error
  WhenOne or more requested files do not exist in the bucket
  ThrowsApiError with HTTP 404 Not Found from the first missing file
  Required handlingCaller MUST handle not found errors. Verify all files exist before starting a batch download, or use skipIfExists option to avoid overwriting local files. A single missing file will fail the entire batch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21]
• TransferManager.downloadFileInChunks · transfer-download-chunks-crc32c-mismatch

  error
  WhenCRC32C validation enabled and assembled file does not match stored checksum
  ThrowsRequestError with code 'CONTENT_DOWNLOAD_MISMATCH'
  Required handlingCaller MUST handle CONTENT_DOWNLOAD_MISMATCH errors when using validation: 'crc32c'. This error means data was corrupted in transit — some downloaded chunks did not assemble correctly. The local file is incomplete or corrupted. Delete the local file and retry the download. Use err.code === 'CONTENT_DOWNLOAD_MISMATCH' to detect this specific error type.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[21]
• TransferManager.downloadFileInChunks · transfer-download-chunks-file-not-found

  error
  WhenFile does not exist in the bucket (fails at metadata fetch stage)
  ThrowsApiError with HTTP 404 Not Found (from file.get() call)
  Required handlingCaller MUST handle not found errors. The download fails at the metadata retrieval stage (before any chunks are downloaded) if the file doesn't exist. No partial files are written to disk at this stage.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21]
• TransferManager.downloadFileInChunks · transfer-download-chunks-partial-chunk-failure

  error
  WhenOne or more chunk downloads fail mid-transfer after file is opened for writing
  ThrowsApiError from the first failed chunk download
  Required handlingCaller MUST handle chunk failures. When a chunk fails, the local file handle is still closed (finally block), but the file on disk will be partially written with missing or corrupted byte ranges. Delete the partially written file before retrying. Do not rely on a partially downloaded file.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[21]
• TransferManager.uploadFileInChunks · transfer-upload-chunks-multipart-error

  error
  WhenAny chunk upload or upload initiation fails
  ThrowsMultiPartUploadError with uploadId and partsMap properties (NOT a standard ApiError)
  Required handlingCaller MUST catch MultiPartUploadError specifically — it is NOT a subclass of ApiError. The error contains two critical properties for resuming: - err.uploadId: the GCS multipart upload ID (to resume the upload later) - err.partsMap: Map of successfully uploaded part numbers to ETags Store these values to resume the upload. Pass them back as options.uploadId and options.partsMap to resume from the last successful chunk. If autoAbortFailure is true (default), the upload is automatically aborted on failure and these fields contain the aborted session — the upload cannot be resumed. Set autoAbortFailure: false to enable resumable failures.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21]
• TransferManager.uploadFileInChunks · transfer-upload-chunks-permission-error

  error
  WhenService account lacks permission to initiate or complete multipart upload
  ThrowsMultiPartUploadError wrapping an underlying 403 Forbidden from GCS XML API
  Required handlingCaller MUST handle permission errors from uploadFileInChunks(). The underlying 403 is wrapped in MultiPartUploadError. Verify service account has storage.objects.create permission. The uploadId in the error will be empty/null if the failure occurred during upload initiation (before any parts were uploaded).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[21]
• combine · combine-source-limit-exceeded

  error
  WhenMore than 32 source objects passed in a single compose request
  ThrowsApiError with HTTP 400 Bad Request from GCS — compose API rejects sources.length > 32
  Required handlingCaller MUST handle the 32-source cap. The GCS compose REST API limits a single request to 32 source components. For larger composes, caller must do a multi-level compose: combine 32 sources into intermediate objects, then combine the intermediates. Without try-catch, the rejection surfaces as an unhandled promise rejection and the partial workflow (e.g. chunked upload assembly) stalls with no remediation hint.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22][23]
• combine · combine-source-not-found

  error
  WhenOne or more source files referenced in sources[] do not exist (HTTP 404)
  ThrowsApiError with HTTP 404 Not Found — naming the missing source object in the message
  Required handlingCaller MUST handle source-missing errors. Compose fails atomically — if any one source object is missing, no destination object is created. This is common when a parallel upload path (e.g. chunked uploadFileInChunks or TransferManager) had a partial failure and the missing chunk was retried under a different name. Distinguish 404 from 403 to avoid silently retrying a request that will always fail.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[23]
• combine · combine-precondition-failed

  warning
  WhenifGenerationMatch on the destination does not match — concurrent compose conflict
  ThrowsApiError with HTTP 412 Precondition Failed
  Required handlingCaller MUST handle 412 precondition failures. When ifGenerationMatch is set on the destination (or via instancePreconditionOpts), a concurrent writer may have updated the destination object since the caller read its generation. Compose becomes a no-op and the caller must re-read destination state and retry — or treat the conflict as a write-loss event. Without explicit handling, a parallel assembly job will silently produce stale output or duplicate the work.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[22][23]
• moveFileAtomic · move-file-atomic-non-hns-bucket

  error
  WhenCalled on a bucket without hierarchical namespace enabled
  ThrowsApiError with HTTP 400 Bad Request — moveTo endpoint rejects non-HNS buckets
  Required handlingCaller MUST handle non-HNS errors with a fallback path. moveFileAtomic only works on HNS buckets — most existing GCS buckets are flat. Catch the 400 and either fall back to file.move() (and accept the non-atomic semantics), or surface a configuration error to operators so they enable HNS at bucket-creation time (HNS cannot be enabled retroactively). Without try-catch, callers silently assume atomicity they do not have.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24][25]
• moveFileAtomic · move-file-atomic-precondition-failed

  error
  WhenifGenerationMatch precondition does not match the destination's current generation
  ThrowsApiError with HTTP 412 Precondition Failed
  Required handlingCaller MUST handle 412 precondition failures. When preconditionOpts.ifGenerationMatch is set, a concurrent writer may have created or updated the destination since the caller's last read. moveFileAtomic does not overwrite — it fails. Without explicit 412 handling, retrying with the same precondition will loop indefinitely; the caller must re-read the destination, decide whether to overwrite, and resubmit.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[25]
• moveFileAtomic · move-file-atomic-source-not-found

  error
  WhenSource file does not exist or was deleted before the move request landed
  ThrowsApiError with HTTP 404 Not Found
  Required handlingCaller MUST handle source-not-found errors. Unlike file.move() (where a 404 in the delete phase is benign), a 404 from moveFileAtomic always means the source never moved — the destination was not created. Treat as a hard failure and investigate whether another worker raced the move or the source was cleaned up prematurely.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[25]
• lock · lock-precondition-failed

  error
  WhenifMetagenerationMatch does not match — bucket metadata changed since caller read it
  ThrowsApiError with HTTP 412 Precondition Failed
  Required handlingCaller MUST handle 412 precondition failures. The lock request includes the metageneration the caller observed; if any other writer mutated bucket metadata between the read and the lock call, the lock is rejected. Without try-catch, the operator sees a generic promise rejection and may retry the lock against stale state — locking the WRONG retention period permanently. Re-fetch getMetadata(), re-confirm the retention period is the intended value, and only then resubmit.
  costcriticalin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[26][27]
• lock · lock-no-retention-policy

  error
  WhenBucket has no retention policy to lock — nothing to lock
  ThrowsApiError with HTTP 400 Bad Request — lockRetentionPolicy on bucket without policy
  Required handlingCaller MUST handle the no-policy case. lock() only works when a retention policy is already set via setRetentionPeriod(). If called on a bucket with no policy, the API returns 400. Without try-catch, the deployment scripts that enforce compliance posture silently believe they locked the bucket — but the bucket has no retention enforcement at all. This is a compliance-audit time bomb. Verify getMetadata().retentionPolicy exists before calling lock().
  costcriticalin prodimmediate exceptionusers seesecurity breachvisibilitysilent
  Sources[26]
• lock · lock-permission-error

  error
  WhenService account lacks storage.buckets.update or the role required to lock retention
  ThrowsApiError with HTTP 403 Forbidden
  Required handlingCaller MUST handle permission errors on lock(). Locking a retention policy requires elevated permissions (typically Storage Admin or a custom role with storage.buckets.update). A silently-swallowed 403 means compliance automation believes locking succeeded but the policy remains mutable. Verify the service account role at deployment time and surface 403s as a hard failure to the compliance owner.
  costhighin prodimmediate exceptionusers seesecurity breachvisibilitysilent
  Sources[27]

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.