apache/beam · error · UnsupportedOperationException

Support for move options is not yet implemented.

Error message

Support for move options is not yet implemented.

What it means

LocalFileSystem.rename throws UnsupportedOperationException whenever any MoveOptions are passed: the local filesystem's rename implementation only supports a plain copy-and-delete and ignores/never implements move-variant semantics (e.g. no-replace). The moveOptions varargs are the input at fault — this is an explicit unimplemented-capability guard, not a data error.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/io/LocalFileSystem.java:172

      }
      // Copy the source file, replacing the existing destination.
      // Paths.get(x) will not work on Windows OSes cause of the ":" after the drive letter.
      Files.copy(
          src.getPath(),
          dst.getPath(),
          StandardCopyOption.REPLACE_EXISTING,
          StandardCopyOption.COPY_ATTRIBUTES);
    }
  }

  @Override
  protected void rename(
      List<LocalResourceId> srcResourceIds,
      List<LocalResourceId> destResourceIds,
      MoveOptions... moveOptions)
      throws IOException {
    if (moveOptions.length > 0) {
      throw new UnsupportedOperationException("Support for move options is not yet implemented.");
    }
    checkArgument(
        srcResourceIds.size() == destResourceIds.size(),
        "Number of source files %s must equal number of destination files %s",
        srcResourceIds.size(),
        destResourceIds.size());
    int numFiles = srcResourceIds.size();
    for (int i = 0; i < numFiles; i++) {
      LocalResourceId src = srcResourceIds.get(i);
      LocalResourceId dst = destResourceIds.get(i);
      LOG.debug("Renaming {} to {}", src, dst);
      File parent = dst.getCurrentDirectory().getPath().toFile();
      if (!parent.exists()) {
        checkArgument(
            parent.mkdirs() || parent.exists(),
            "Unable to make output directory %s in order to move into file %s",
            parent,
            dst.getPath());

View on GitHub (pinned to 12126d8942)

Solutions

  1. Call rename without MoveOptions when using LocalFileSystem
  2. Guard the call: only pass MoveOptions for filesystems that support them (check the implementation)
  3. Handle local moves yourself with java.nio.file.Files.move if you need option-like semantics

Example fix

// before
FileSystems.rename(srcs, dests, MoveOptions.IGNORE_MISSING_TARGETS);
// after
if (isLocalScheme(srcs.get(0))) {
  FileSystems.rename(srcs, dests); // no options
} else {
  FileSystems.rename(srcs, dests, MoveOptions.IGNORE_MISSING_TARGETS);
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Only pass MoveOptions for filesystems known to support them
boolean local = "file".equals(URI.create(srcResourceIds.get(0).toString()).getScheme());
if (local && moveOptions.length > 0) {
  throw new IllegalArgumentException("LocalFileSystem does not support MoveOptions");
}

Try / catch

try {
  FileSystems.rename(srcs, dests, moveOptions);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("move options")) {
    FileSystems.rename(srcs, dests); // fall back to plain rename
  } else {
    throw e;
  }
}

Prevention

When it happens

Trigger: Calling FileSystems.rename(srcList, destList, MoveOptions... ) with non-empty move options while the underlying filesystem is the LocalFileSystem — e.g. requesting IGNORE_MISSING_TARGETS or SKIP_DIRECTORY_TREES on local paths.

Common situations: Writing generic rename code that passes MoveOptions for cloud filesystems but is exercised against local files in tests; new code using options introduced for other FileSystem implementations.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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