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.

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)

Solutions

1. Check the underlying IOException cause for the accelerator's real failure (credentials, region, object access).
2. Disable the analytics accelerator by unsetting s3.analytics-accelerator.* properties to fall back to the default S3InputStream.
3. Verify the S3 URI and that the object exists and is readable by the configured credentials.
4. 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

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

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
}

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

• An error occurred while closing the stream
• An error occurred while aborting the stream
• Failed to close S3SeekableInputStreamFactory
• Cannot initialize S3FileIOAwsClientFactory, missing no-arg c
• Cannot initialize S3FileIOAwsClientFactory, %s does not impl

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