{"record":{"id":"477d6fdadbf3b2d9","repo":"apache/hadoop","slug":"error-accessing-bucket-s","errorCode":null,"errorMessage":"Error accessing Bucket %s","messagePattern":"Error accessing Bucket (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/GoogleCloudStorage.java","lineNumber":197,"sourceCode":"\n  /**\n   * Gets the bucket with the given name.\n   *\n   * @param bucketName name of the bucket to get\n   * @return the bucket with the given name or null if bucket not found\n   * @throws IOException if the bucket exists but cannot be accessed\n   */\n  @Nullable\n  private Bucket getBucket(String bucketName) throws IOException {\n    LOG.debug(\"getBucket({})\", bucketName);\n    checkArgument(!isNullOrEmpty(bucketName), \"bucketName must not be null or empty\");\n    try {\n      return storage.get(bucketName);\n    } catch (StorageException e) {\n      if (ErrorTypeExtractor.getErrorType(e) == ErrorTypeExtractor.ErrorType.NOT_FOUND) {\n        return null;\n      }\n      throw new IOException(\"Error accessing Bucket \" + bucketName, e);\n    }\n  }\n\n  private static GoogleCloudStorageItemInfo createItemInfoForBlob(StorageResourceId resourceId,\n      Blob blob) {\n    checkArgument(resourceId != null, \"resourceId must not be null\");\n    checkArgument(blob != null, \"object must not be null\");\n    checkArgument(resourceId.isStorageObject(),\n        \"resourceId must be a StorageObject. resourceId: %s\", resourceId);\n    checkArgument(resourceId.getBucketName().equals(blob.getBucket()),\n        \"resourceId.getBucketName() must equal object.getBucket(): '%s' vs '%s'\",\n        resourceId.getBucketName(), blob.getBucket());\n    checkArgument(resourceId.getObjectName().equals(blob.getName()),\n        \"resourceId.getObjectName() must equal object.getName(): '%s' vs '%s'\",\n        resourceId.getObjectName(), blob.getName());\n\n    Map<String, byte[]> decodedMetadata =\n        blob.getMetadata() == null ? null : decodeMetadata(blob.getMetadata());","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/GoogleCloudStorage.java#L179-L215","documentation":"getBucket(bucketName) fetches bucket metadata via storage.get(); a StorageException classified NOT_FOUND returns null (mapped to 'bucket absent'), but every other StorageException is rethrown as IOException(\"Error accessing Bucket \" + bucketName) with the original cause attached. This message therefore means the buckets.get call failed for a non-404 reason: permissions, auth, network, or API disabled.","triggerScenarios":"Calling getItemInfo/listStatus on a bucket-root path, or the existence check inside copy validation, when the service account lacks storage.buckets.get; using a malformed or mis-scoped bucket name; the GCS JSON API being unavailable or the project misconfigured.","commonSituations":"Service account granted only object-level (storage.objects.*) roles but not Reader on the bucket; typo'd bucket name in gs:// URL; private key JSON for a different project; GCS API not enabled on the project.","solutions":["Grant the service account roles/storage.objectViewer (or at least buckets.get) on the bucket and retry","Verify the bucket name and project with gsutil ls gs://<bucket> using the same credentials","Inspect the nested StorageException cause for its code/reason (403 PERMISSION_DENIED vs network) and address it","Confirm the auth key (google.cloud.auth.service.account.json.keyfile) points at the right project"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  Bucket b = gcs.getBucket(bucketName);\n} catch (IOException e) {\n  if (e.getMessage().startsWith(\"Error accessing Bucket \")) {\n    StorageException cause = (StorageException) e.getCause();\n    if (cause.getCode() == 403) { /* grant storage.buckets.get */ }\n  }\n  throw e;\n}","preventionTips":["Grant the service account bucket-level read (objectViewer) in addition to object access","Validate bucket names in gs:// URLs early (typos surface here as access errors)","Test bucket visibility with gsutil under the job's credentials before running pipelines"],"tags":["gcs","hadoop-gcp","bucket-metadata","permissions","storageexception"],"backgroundTag":"bucket-access-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}