apache/iceberg · error · RuntimeIOException

Failed to create S3 analytics accelerator input stream for

Error message

Failed to create S3 analytics accelerator input stream for: %s

What it means

RuntimeIOException thrown by AnalyticsAcceleratorUtil.newStream when the S3 analytics accelerator factory fails to create the seekable input stream for a file (IOException from factory.createStream). The analytics accelerator wraps S3 reads with a prefetching/caching layer; a failure to initialize the stream for the given S3 URI is surfaced as an unchecked RuntimeIOException with the file URI in the message.

Solutions

Check the underlying IOException cause for the accelerator's real failure (credentials, region, object access).
Disable the analytics accelerator by unsetting s3.analytics-accelerator.* properties to fall back to the default S3InputStream.
Verify the S3 URI and that the object exists and is readable by the configured credentials.
Align the analytics-accelerator library version with the Iceberg AWS module version in use.

Example fix

// before
Map<String, String> props = Map.of(
    S3FileIOProperties.ANALYTICS_ACCELERATOR_ENABLED, "true",
    "s3.analytics-accelerator.bucket.REGION_MISMATCH", "us-west-1"); // stream creation fails
// after
Map<String, String> props = Map.of(); // default S3 input stream, or fix accelerator region config

Defensive patterns

Strategy: fallback

Validate before calling

if (properties.containsKey("s3.analytics-accelerator.enabled")) {
  // verify accelerator config/credentials before enabling
}

Try / catch

try {
  stream = AnalyticsAcceleratorUtil.newStream(inputFile, props);
} catch (RuntimeIOException e) {
  LOG.warn("Accelerator stream failed, falling back to default S3 stream", e);
  stream = new S3InputStream(...); // default path
}

Prevention

Validate accelerator credentials/region configuration before enabling
Test S3 object accessibility with plain S3FileIO first
Pin compatible analytics-accelerator library versions
Keep the default (non-accelerator) path as an operational fallback

When it happens

Trigger: S3FileIO opening a data/metadata file with analytics accelerator enabled (s3.analytics-accelerator.* properties) while factory.createStream(uri) throws IOException — e.g. accelerator client initialization failure or invalid/unsupported URI.

Common situations: Misconfigured analytics accelerator options (bucket/region mismatch, credentials for the accelerator's async client); accelerator library version incompatibility; object missing or inaccessible when the stream is created; bad s3:// URI format.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/9b966e9ce9d3f52c. Report an issue: GitHub.

Appendix: source

Thrown at aws/src/main/java/org/apache/iceberg/aws/s3/AnalyticsAcceleratorUtil.java:68

                          Pair<S3AsyncClient, S3FileIOProperties>, S3SeekableInputStreamFactory>)
                      (key, factory, cause) -> close(factory))
              .build();

  private AnalyticsAcceleratorUtil() {}

  public static SeekableInputStream newStream(S3InputFile inputFile) {
    S3URI uri = S3URI.of(inputFile.uri().bucket(), inputFile.uri().key());

    S3SeekableInputStreamFactory factory =
        STREAM_FACTORY_CACHE.get(
            Pair.of(inputFile.asyncClient(), inputFile.s3FileIOProperties()),
            AnalyticsAcceleratorUtil::createNewFactory);

    try {
      S3SeekableInputStream seekableInputStream = factory.createStream(uri);
      return new AnalyticsAcceleratorInputStreamWrapper(seekableInputStream, inputFile.metrics());
    } catch (IOException e) {
      throw new RuntimeIOException(
          e, "Failed to create S3 analytics accelerator input stream for: %s", inputFile.uri());
    }
  }

  private static S3SeekableInputStreamFactory createNewFactory(
      Pair<S3AsyncClient, S3FileIOProperties> cacheKey) {
    ConnectorConfiguration connectorConfiguration =
        new ConnectorConfiguration(cacheKey.second().s3AnalyticsacceleratorProperties());
    S3SeekableInputStreamConfiguration streamConfiguration =
        S3SeekableInputStreamConfiguration.fromConfiguration(connectorConfiguration);
    ObjectClientConfiguration objectClientConfiguration =
        ObjectClientConfiguration.fromConfiguration(connectorConfiguration);

    ObjectClient objectClient = new S3SdkObjectClient(cacheKey.first(), objectClientConfiguration);
    return new S3SeekableInputStreamFactory(objectClient, streamConfiguration);
  }

  private static void close(S3SeekableInputStreamFactory factory) {

View on GitHub (pinned to 86d9c8fc54)