apache/hadoop · critical · UnknownStoreException

Bucket does not exist. Accessing with fs.s3a.endpoint set t

Error message

 Bucket does not exist. Accessing with fs.s3a.endpoint set to <endpoint>

What it means

Thrown by S3AFileSystem.verifyBucketExists() during initialize(): a headBucket probe returned HTTP 404, or 403 when the bucket name is an S3 access point, so no bucket with that name is visible at the configured endpoint. The FileSystem cannot be constructed and every later operation is blocked. The message deliberately includes the s3a://bucket/ URI and the fs.s3a.endpoint value to make endpoint/bucket mismatches diagnosable.

Source

Thrown at hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/S3AFileSystem.java:1062

    if(!trackDurationAndSpan(
        STORE_EXISTS_PROBE, bucket, null, () ->
            invoker.retry("doesBucketExist", bucket, true, () -> {
              try {
                getS3Client().headBucket(HeadBucketRequest.builder().bucket(bucket).build());
                return true;
              } catch (AwsServiceException ex) {
                int statusCode = ex.statusCode();
                if (statusCode == SC_404_NOT_FOUND ||
                    (statusCode == SC_403_FORBIDDEN && accessPoint != null)) {
                  return false;
                }
              }

              return true;
            }))) {

      throw new UnknownStoreException("s3a://" + bucket + "/",
          " Bucket does " + "not exist. " + "Accessing with " + ENDPOINT + " set to "
              + getConf().getTrimmed(ENDPOINT, null));
    }
  }

  /**
   * Get S3A Instrumentation. For test purposes.
   * @return this instance's instrumentation.
   */
  @VisibleForTesting
  public S3AInstrumentation getInstrumentation() {
    return instrumentation;
  }

  /**
   * Get FS Statistic for this S3AFS instance.
   *
   * @return FS statistic instance.

View on GitHub (pinned to 2add963021)

Solutions

Verify and fix the bucket name, and create the bucket if missing (aws s3api head-bucket / aws s3 mb s3://<bucket>)
Set fs.s3a.endpoint.region (and fs.s3a.endpoint for non-AWS stores) to the region that actually hosts the bucket
For access points, confirm the ARN and that the credentials have permission on it - a 403 is treated as 'bucket absent'
Check credentials and endpoint routing: a mis-signed request can surface as a missing bucket

Example fix

<!-- before: bucket is in eu-west-1, client signs for us-east-1 -->
<property><name>fs.s3a.endpoint.region</name><value>us-east-1</value></property>

<!-- after -->
<property><name>fs.s3a.endpoint.region</name><value>eu-west-1</value></property>

Defensive patterns

Strategy: try-catch

Validate before calling

// Preflight before handing the FileSystem to a long job
try {
  FileSystem fs = FileSystem.get(new URI("s3a://" + bucket + "/"), conf);
} catch (UnknownStoreException e) {
  throw new IOException("Bucket " + bucket + " absent or wrong endpoint: " + e.getMessage(), e);
}

Type guard

static boolean isUnknownStore(Throwable t) {
  return t instanceof org.apache.hadoop.fs.UnknownStoreException;
}

Try / catch

When creating the FileSystem, catch UnknownStoreException separately and before IOException: it is a deterministic configuration error - fail fast with the bucket/endpoint in the message; do not retry it.

Prevention

Provision and verify buckets (aws s3api head-bucket) before jobs run
Pin fs.s3a.endpoint.region to the bucket's region in core-site.xml
Validate bucket names from user input before building s3a:// URIs
In CI, assert the store endpoint is reachable before the suite starts

When it happens

Trigger: FileSystem.get() or any path qualification for s3a://<bucket>/ where the bucket does not exist at the endpoint reached by the client; fs.s3a.endpoint pointing at the wrong region or at a third-party store (MinIO, Ceph) where the bucket was never created; using an access point ARN whose 403 is interpreted as 'not found'.

Common situations: Typo in the bucket name in a job URL; bucket deleted or owned by another account; fs.s3a.endpoint/fs.s3a.endpoint.region left stale after a region migration; integration tests against a containerized S3 that was restarted without recreating buckets.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/2a6d195cda198424. Report an issue: GitHub.