apache/beam · error · IllegalStateException

Creation of file on path

Error message

Creation of file on path %s failed

What it means

HDFSSynchronization.tryCreateFile() creates the lock/flag file on HDFS; any IOException other than AlreadyBeingCreatedException is wrapped in IllegalStateException("Creation of file on path %s failed"). It means the synchronization primitive could not create its marker file.

Solutions

1. Verify the parent directory exists and the job user has write permission on it (hdfs dfs -chmod/-chown as needed).
2. Check NameNode health and safe-mode status; wait for safe mode to exit or fix fs.defaultFS misconfiguration.
3. Retry acquisition with backoff; transient network errors to HDFS often resolve.
4. Ensure the synchronization directory is pre-created by setup code before workers start.

Example fix

// before
TaskID id = sync.acquireTaskIdLock(conf);
// after
Path syncDir = sync.getJobLockPath(conf); // ensure exists & writable first
fs.mkdirs(syncDir);
TaskID id = sync.acquireTaskIdLock(conf);

Path dir = path.getParent();
if (!fs.exists(dir)) fs.mkdirs(dir);
fs.access(dir, FsAction.WRITE); // throws if not writable

null

try { sync.acquireTaskIdLock(conf); } catch (IllegalStateException e) { retryWithBackoff(() -> sync.acquireTaskIdLock(conf)); }

When it happens

Trigger: tryAcquireJobLock, acquireTaskIdLock, or acquireTaskAttemptIdLock invoke tryCreateFile and HDFS create throws IOException — permission denied, parent directory missing, NameNode unavailable, or disk/quota errors.

Common situations: Missing HDFS write permissions for the job user; the sync base directory was never created; NameNode in safe mode or failover; HDFS quota exceeded.

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

• Could not create the new requirements file
• Delete of lock directory
• RCSP : Subsequent run that doesn't hold the lock . This is…
• 2xx codes should not be exceptions. Got status code
• A 'datagen' table requires either 'rows-per-second' (for…

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/4189a14df57bb9b5. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/hadoop-format/src/main/java/org/apache/beam/sdk/io/hadoop/format/HDFSSynchronization.java:161

    return HadoopFormats.createTaskAttemptID(jobId, taskId, taskAttemptCandidate);
  }

  private boolean tryCreateFile(Configuration conf, Path path) {
    try (FileSystem fileSystem = fileSystemFactory.apply(conf)) {
      try {
        return fileSystem.createNewFile(path);
      } catch (FileAlreadyExistsException | org.apache.hadoop.fs.FileAlreadyExistsException e) {
        return false;
      } catch (RemoteException e) {
        // remote hdfs exception
        if (e.getClassName().equals(AlreadyBeingCreatedException.class.getName())) {
          return false;
        }
        throw e;
      }
    } catch (IOException e) {
      throw new IllegalStateException(String.format("Creation of file on path %s failed", path), e);
    }
  }

  private String getJobJtIdentifier(Configuration conf) {
    JobID job =
        Preconditions.checkNotNull(
            HadoopFormats.getJobId(conf),
            "Configuration must contain jobID under key %s.",
            HadoopFormatIO.JOB_ID);
    return job.getJtIdentifier();
  }

  /**
   * Function which can throw exception.
   *
   * @param <T1> parameter type
   * @param <T2> result type
   * @param <X> exception type

View on GitHub (pinned to 12126d8942)