Service: storagebatchoperations.googleapis.com
When facing errors, refer to this catalog alongside using our client libraries. If you're using your own libraries, keep this guide handy for debugging and error resolution. To know more about the error response structure, visit the error overview page.
Error codes
The following table lists HTTP status codes and associated errors that you might encounter when interacting with our API. Each status code corresponds to one or more reasons and descriptions to help you troubleshoot and handle errors effectively in your application. Within the descriptions, variables denoted by curly braces ({}) represent placeholders for values that are specific to your request.
| Reason | HTTP Status Code | Description |
|---|---|---|
JOB_ID_INVALID |
400 |
The 'job_id' is invalid. The job ID must match the pattern [a-z0-9]([-a-z0-9]*[a-z0-9])?. For more information, see our Troubleshooting documentation. |
RESOURCE_NAME_TOO_LONG |
400 |
The resource name exceeds the maximum allowed length of {max_length} bytes. For more information, see our Troubleshooting documentation. |
DESCRIPTION_TOO_LONG |
400 |
The job 'description' exceeds the maximum allowed length of {max_length} bytes. For more information, see our Troubleshooting documentation. |
SOURCE_NOT_SPECIFIED |
400 |
A source ('bucket_list' or 'project_source') must be specified for the job. For more information, see our Troubleshooting documentation. |
TRANSFORMATION_NOT_SPECIFIED |
400 |
A transformation must be specified for the job. Specify exactly one transformation: 'delete_object', 'put_object_hold', 'put_metadata', 'rewrite_object', 'update_object_custom_context', 'set_object_acls', or 'drop_object_google_context'. For more information, see our Troubleshooting documentation. |
BUCKET_LIST_EMPTY |
400 |
The 'bucket_list' must not be empty. Specify at least one bucket configuration. For more information, see our Troubleshooting documentation. |
TOO_MANY_BUCKETS |
400 |
The 'bucket_list' must not exceed {max_buckets} buckets. For more information, see our Troubleshooting documentation. |
BUCKET_NAME_REQUIRED |
400 |
The 'bucket' field must be specified in the bucket configuration. For more information, see our Troubleshooting documentation. |
OBJECT_CONFIGURATION_REQUIRED |
400 |
An object configuration ('prefix_list', 'manifest', or 'project_source') must be specified in the bucket operation. For more information, see our Troubleshooting documentation. |
MANIFEST_LOCATION_REQUIRED |
400 |
The 'manifest_location' field must be specified. For more information, see our Troubleshooting documentation. |
MANIFEST_LOCATION_INVALID |
400 |
The manifest location '{manifest_location}' is invalid. The location must follow the format gs://<bucket_name>/<path>/<object_name>.csv where <path> is optional and <object_name> is followed by .csv and contains at most one wildcard character ('*'). For more information, see our Troubleshooting documentation. |
BUCKET_NAME_INVALID |
400 |
The bucket name '{bucket_name}' does not conform to Cloud Storage bucket naming requirements. For more information, see our Troubleshooting documentation. |
OBJECT_NAME_INVALID |
400 |
The object name '{object_name}' does not conform to Cloud Storage object naming requirements. For more information, see our Troubleshooting documentation. |
OBJECT_PREFIX_INVALID_UTF8 |
400 |
The object prefix contains invalid UTF-8 characters. Ensure that the prefix is valid UTF-8. For more information, see our Troubleshooting documentation. |
OBJECT_PREFIX_TOO_LONG |
400 |
The object prefix exceeds the maximum allowed length of {max_length} bytes. For more information, see our Troubleshooting documentation. |
OBJECT_PREFIX_INVALID_CHARACTER |
400 |
The object prefix contains an invalid newline or carriage return character. For more information, see our Troubleshooting documentation. |
OBJECT_PREFIX_OVERLAP |
400 |
The object prefix '{prefix_1}' overlaps with '{prefix_2}'. Object prefixes must not be prefixes of other included prefixes. For more information, see our Troubleshooting documentation. |
DUPLICATE_OBJECT_PREFIX |
400 |
Duplicate object prefix '{object_prefix}' found in 'included_object_prefixes'. Remove the duplicate entry. For more information, see our Troubleshooting documentation. |
TOO_MANY_OBJECT_PREFIXES |
400 |
The 'prefix_list' must not exceed {max_prefixes} included object prefixes. For more information, see our Troubleshooting documentation. |
PROJECT_SOURCE_DRY_RUN_ID_INVALID |
400 |
The 'dry_run_job_id' is invalid. The job ID must match the pattern [a-z0-9]([-a-z0-9]*[a-z0-9])?. For more information, see our Troubleshooting documentation. |
PROJECT_SOURCE_DRY_RUN_FIELDS_EXCLUSIVE |
400 |
When 'dry_run_job_id' is specified, all other fields in 'ProjectSource' must be empty. For more information, see our Troubleshooting documentation. |
PROJECT_SOURCE_PROJECT_INVALID |
400 |
The project '{project}' is invalid. The project must follow the format 'projects/{project_number}' or 'projects/{project_id}'. For more information, see our Troubleshooting documentation. |
INSIGHTS_DATASET_CONFIG_INVALID |
400 |
The insights dataset configuration '{insights_dataset_config}' is invalid. The configuration resource name must follow the format 'projects/{project}/locations/{location}/datasetConfigs/{dataset_config}'. For more information, see our Troubleshooting documentation. |
TARGET_LOCATIONS_REQUIRED_FOR_SNAPSHOT_TIME |
400 |
The 'locations' field in 'target_locations' must be specified when 'snapshot_time' is provided. For more information, see our Troubleshooting documentation. |
TOO_MANY_TARGET_LOCATIONS |
400 |
The 'target_locations' list must not exceed {max_locations} locations. For more information, see our Troubleshooting documentation. |
CEL_EXPRESSION_TOO_LONG |
400 |
The filter expression must not exceed {max_length} bytes. For more information, see our Troubleshooting documentation. |
KMS_KEY_INVALID |
400 |
The KMS key is invalid. The key must follow the format 'projects/{project}/locations/{location}/keyRings/{keyring}/cryptoKeys/{key}'. For more information, see our Troubleshooting documentation. |
REWRITE_OBJECT_MISSING_PARAMETERS |
400 |
At least one of 'storage_class' or 'kms_key' must be specified for 'RewriteObject'. For more information, see our Troubleshooting documentation. |
PUT_OBJECT_HOLD_MISSING_PARAMETERS |
400 |
At least one of 'temporary_hold' or 'event_based_hold' must be specified. For more information, see our Troubleshooting documentation. |
PUT_METADATA_MISSING_PARAMETERS |
400 |
At least one field in 'PutMetadata' must be specified. For more information, see our Troubleshooting documentation. |
RETAIN_UNTIL_TIME_REQUIRED |
400 |
The 'retain_until_time' field must be specified in RFC 3339 format when 'retention_mode' is set. For more information, see our Troubleshooting documentation. |
RETENTION_MODE_REQUIRED |
400 |
The 'retention_mode' field must be set to 'LOCKED' or 'UNLOCKED'. For more information, see our Troubleshooting documentation. |
RETAIN_UNTIL_TIME_INVALID_FORMAT |
400 |
The 'retain_until_time' field must be in RFC 3339 timestamp format (for example, '2026-12-31T23:59:59Z'). For more information, see our Troubleshooting documentation. |
CUSTOM_CONTEXT_KEY_CONFLICT |
400 |
The same key cannot be specified in both 'updates' and 'keys_to_clear'. For more information, see our Troubleshooting documentation. |
UPDATE_OBJECT_CUSTOM_CONTEXT_MISSING_ACTION |
400 |
At least one action in 'UpdateObjectCustomContext' must be specified. If 'clear_all' is specified, it must be set to true. For more information, see our Troubleshooting documentation. |
SET_OBJECT_ACLS_MISSING_ACTION |
400 |
At least one of 'grants' or 'remove_entities' must be specified in 'SetObjectAcls'. For more information, see our Troubleshooting documentation. |
UNSUPPORTED_ACL_ENTITY |
400 |
The entity '{entity}' is unsupported. Only 'allUsers' and 'allAuthenticatedUsers' are supported. For more information, see our Troubleshooting documentation. |
ACL_ENTITY_CONFLICT |
400 |
The same entity cannot be specified in both 'grants' and 'remove_entities'. For more information, see our Troubleshooting documentation. |
AUTOCLASS_STORAGE_CLASS_TRANSFORMATION_UNSUPPORTED |
400 |
Storage class transformations cannot be performed on Autoclass-enabled buckets. Disable Autoclass on the bucket or remove the storage class transformation. For more information, see our Troubleshooting documentation. |
UBLA_OBJECT_ACL_UPDATE_UNSUPPORTED |
400 |
Cannot update access control lists (ACLs) for objects in a bucket with uniform bucket-level access enabled. Manage access using IAM permissions instead. For more information, see our Troubleshooting documentation. |
BUCKET_DISCOVERY_INSIGHTS_DATASET_NOT_FOUND |
404 |
Failed to perform bucket discovery. The 'insights_dataset_config' cannot be found. Verify that the insights dataset exists and is accessible. For more information, see our Troubleshooting documentation. |
BUCKET_DISCOVERY_SNAPSHOT_TOO_OLD |
400 |
Failed to perform bucket discovery. The latest dataset snapshot time is older than two days. Verify that the dataset configuration is active and generating snapshots, specify 'snapshot_time' and 'target_locations' overrides, or use a CSV manifest instead. For more information, see our Troubleshooting documentation. |
BUCKET_DISCOVERY_TOO_MANY_BUCKETS |
400 |
Failed to perform bucket discovery. Too many buckets discovered. Only 1,000 buckets are supported. For more information, see our Troubleshooting documentation. |