apache/beam · error · IllegalStateException

Unknown mode: " + mode

Error message

Unknown mode: " + mode

What it means

FileBasedSource.validate() throws IllegalStateException when the source's Mode is neither FILEPATTERN nor SINGLE_FILE_OR_SUBRANGE. validate() runs before reader creation (createReader calls it), so this aborts pipeline execution when the source's mode is corrupted or unrecognized.

Source

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

    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());
        break;
      case SINGLE_FILE_OR_SUBRANGE:
        // Nothing more to validate.
        break;
      default:
        throw new IllegalStateException("Unknown mode: " + mode);
    }
  }

  @Override
  public final long getMaxEndOffset(PipelineOptions options) throws IOException {
    checkArgument(
        mode != Mode.FILEPATTERN, "Cannot determine the exact end offset of a file pattern");
    Metadata metadata = getSingleFileMetadata();
    return metadata.sizeBytes();
  }

  /**
   * A {@link Source.Reader reader} that implements code common to readers of {@code
   * FileBasedSource}s.
   *
   * <h2>Seekability</h2>
   *
   * <p>This reader uses a {@link ReadableByteChannel} created for the file represented by the

View on GitHub (pinned to 12126d8942)

Solutions

1. Align Beam SDK versions across client and workers.
2. Resubmit a freshly built pipeline.
3. If subclassing FileBasedSource, only use Mode.FILEPATTERN or Mode.SINGLE_FILE_OR_SUBRANGE.

When it happens

Trigger: Creating a reader for a FileBasedSource whose mode is an unrecognized value — typically SDK version skew between the job-submission graph and worker deserialization, or a subclass violating the mode contract.

Common situations: Same as 195: mixed Beam versions across client/workers, stale serialized pipelines, or custom FileBasedSource subclasses misusing the mode field.

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

• Unexpected 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/783fec0a6f7bf2fc. Report an issue: GitHub.