apache/beam · warning · IllegalStateException

Unexpected mode: " + mode

Error message

Unexpected mode: " + mode

What it means

FileBasedSource.toString() throws IllegalStateException when the source's Mode enum is neither FILEPATTERN nor SINGLE_FILE_OR_SUBRANGE. Since Mode has only these values, hitting this indicates internal state corruption or a new mode added without updating this switch.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileBasedSource.java:412

          System.currentTimeMillis() - startTime);
      if (fileReaders.size() == 1) {
        return fileReaders.get(0);
      }
      return new FilePatternReader(this, fileReaders);
    } else {
      return createSingleFileReader(options);
    }
  }

  @Override
  public String toString() {
    switch (mode) {
      case FILEPATTERN:
        return fileOrPatternSpec.toString();
      case SINGLE_FILE_OR_SUBRANGE:
        return fileOrPatternSpec + " range " + super.toString();
      default:
        throw new IllegalStateException("Unexpected mode: " + mode);
    }
  }

  @Override
  public void validate() {
    super.validate();
    switch (mode) {
      case FILEPATTERN:
        checkArgument(
            getStartOffset() == 0,
            "FileBasedSource is based on a file pattern or a full single file "
                + "but the starting offset proposed %s is not zero",
            getStartOffset());
        checkArgument(
            getEndOffset() == Long.MAX_VALUE,
            "FileBasedSource is based on a file pattern or a full single file "
                + "but the ending offset proposed %s is not Long.MAX_VALUE",
            getEndOffset());

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure all workers and the submitting client use the same Beam SDK version.
2. Rebuild the pipeline and resubmit; clear stale serialized job graphs.
3. If you added a custom Mode constant, update toString()'s switch.

When it happens

Trigger: Calling toString() on a FileBasedSource whose mode field is an unexpected value — practically only via SDK version mismatch, deserialization of a foreign mode constant, or reflection.

Common situations: Debugging/logging a source object after SDK version skew between workers, or deserializing a pipeline graph serialized with a different Beam version.

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

• Unknown mode: " + mode
• Encountered unknown AtomicType: +protoFieldType.getAtomicTyp
• Thread pool not initialized for UUID:
• Processing elements map not initialized for UUID:
• Buffer counter not initialized for UUID:

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