apache/iceberg · error · RuntimeIOException

Failed to create Parquet output file for %s

Error message

Failed to create Parquet output file for %s

What it means

ParquetIO.file(OutputFile) adapts Iceberg OutputFiles to Parquet OutputFiles. For HadoopOutputFile instances it reconstructs the Parquet HadoopOutputFile from the path; an IOException during that operation is rethrown as RuntimeIOException with this message, meaning the Parquet output target could not be created.

Source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/ParquetIO.java:76

      try {
        return org.apache.parquet.hadoop.util.HadoopInputFile.fromStatus(
            hfile.getStat(), hfile.getConf());
      } catch (IOException e) {
        throw new RuntimeIOException(
            e, "Failed to create Parquet input file for %s", file.location());
      }
    }
    return new ParquetInputFile(file);
  }

  static OutputFile file(org.apache.iceberg.io.OutputFile file) {
    if (file instanceof HadoopOutputFile) {
      HadoopOutputFile hfile = (HadoopOutputFile) file;
      try {
        return org.apache.parquet.hadoop.util.HadoopOutputFile.fromPath(
            hfile.getPath(), hfile.getConf());
      } catch (IOException e) {
        throw new RuntimeIOException(
            e, "Failed to create Parquet output file for %s", file.location());
      }
    }
    return new ParquetOutputFile(file);
  }

  static OutputFile file(org.apache.iceberg.io.OutputFile file, Configuration conf) {
    if (file instanceof HadoopOutputFile) {
      HadoopOutputFile hfile = (HadoopOutputFile) file;
      try {
        return org.apache.parquet.hadoop.util.HadoopOutputFile.fromPath(hfile.getPath(), conf);
      } catch (IOException e) {
        throw new RuntimeIOException(
            e, "Failed to create Parquet output file for %s", file.location());
      }
    }
    return new ParquetOutputFile(file);
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the RuntimeIOException cause for the underlying Hadoop IOException
2. Verify the destination path and parent directory are valid and writable
3. Check filesystem credentials/connectivity (HDFS, S3, etc.)
4. Ensure no conflicting file creation permissions or existing commit artifacts block the path

Path parent = path.getParent();
if (!fs.exists(parent)) { fs.mkdirs(parent); }
if (!fs.isFileAccessWritable(parent)) { throw new AccessControlException(parent.toString()); }

try {
  ParquetWriter writer = ParquetAppenderWriter = ParquetIO.file(outputFile);
} catch (RuntimeIOException e) {
  logger.error("Output target unusable: {}", outputFile.location(), e.getCause());
  throw e;
}

When it happens

Trigger: Calling ParquetIO.file(OutputFile) with a HadoopOutputFile whose fromPath resolution fails (invalid path, filesystem error, permissions) — thrown as RuntimeIOException.

Common situations: Writing to a nonexistent directory, missing write permissions, HDFS/S3 outages or misconfigured credentials during a write job.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Failed to create file: %s
• Failed to create Parquet input file for %s
• Failed to start Parquet file writer
• Failed to read from input stream
• Failed to read bytes from stream

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