apache/beam · error · UnsupportedOperationException

Unknown DirectoryTreatment: " + directoryTreatment

Error message

Unknown DirectoryTreatment: " + directoryTreatment

What it means

FileIO's directory-treatment switch encountered a DirectoryTreatment value it does not recognize. This is an internal invariant violation: the enum should only contain SKIP, PROHIBIT, or ALLOW, so the default branch indicates a newly added enum constant without matching handling, or corrupted state.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileIO.java:878

    /**
     * @return True if metadata is a directory and directory Treatment is SKIP.
     * @throws java.lang.IllegalArgumentException if metadata is a directory and directoryTreatment
     *     is Prohibited.
     * @throws java.lang.UnsupportedOperationException if metadata is a directory and
     *     directoryTreatment is not SKIP or PROHIBIT.
     */
    static boolean shouldSkipDirectory(
        MatchResult.Metadata metadata, DirectoryTreatment directoryTreatment) {
      if (metadata.resourceId().isDirectory()) {
        switch (directoryTreatment) {
          case SKIP:
            return true;
          case PROHIBIT:
            throw new IllegalArgumentException(
                "Trying to read " + metadata.resourceId() + " which is a directory");

          default:
            throw new UnsupportedOperationException(
                "Unknown DirectoryTreatment: " + directoryTreatment);
        }
      }

      return false;
    }

    /**
     * Converts metadata to readableFile. Make sure {@link
     * #shouldSkipDirectory(org.apache.beam.sdk.io.fs.MatchResult.Metadata,
     * org.apache.beam.sdk.io.FileIO.ReadMatches.DirectoryTreatment)} returns false before using.
     */
    static ReadableFile matchToReadableFile(
        MatchResult.Metadata metadata, Compression compression) {

      compression =
          (compression == Compression.AUTO)
              ? Compression.detect(metadata.resourceId().getFilename())

View on GitHub (pinned to 12126d8942)

Solutions

Upgrade or align all Beam modules to the same version so enum and switch match
Check the classpath for duplicate/mixed org.apache.beam artifacts (mvn dependency:tree)
If you added a new DirectoryTreatment constant, add a case for it in shouldSkipDirectory

Example fix

// before
case ALLOW:
  return false;
default:
  throw new UnsupportedOperationException("Unknown DirectoryTreatment: " + directoryTreatment);
// after
// align beam-sdks-java-core version across all modules, or:
case NEW_TREATMENT:
  return /* new behavior */ false;

Defensive patterns

Strategy: validation

Validate before calling

// Ensure enum and handling stay in sync: exhaustiveness via switching without default
switch (directoryTreatment) {
  case SKIP: case PROHIBIT: case ALLOW: break;
  default: throw new IllegalStateException("Unhandled: " + directoryTreatment);
}

Type guard

boolean isKnownTreatment(DirectoryTreatment t) {
  return t == DirectoryTreatment.SKIP
      || t == DirectoryTreatment.PROHIBIT
      || t == DirectoryTreatment.ALLOW;
}

Try / catch

try {
  fileIOTransform.expand(input);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Unknown DirectoryTreatment")) {
    throw new IllegalStateException("Beam version mismatch on DirectoryTreatment", e);
  }
  throw e;
}

Prevention

Keep all org.apache.beam artifacts at the same version
Run enforcer plugin rules to ban mixed Beam versions
Add a unit test covering every DirectoryTreatment constant
Avoid constructing enums reflectively

When it happens

Trigger: Calling FileIO read/match transforms whose configured DirectoryTreatment falls through the switch in shouldSkipDirectory — practically only possible if a new DirectoryTreatment constant was added to the enum without updating shouldSkipDirectory, or via binary-incompatible mixing of Beam versions.

Common situations: Mixing Beam jars of different versions on the classpath where one version added an enum constant; shading/relocation issues; custom code constructing the enum reflectively.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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