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.

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
• Buffer counter not initialized for UUID:
• Class has no path back to any root class. It should never…
• Class is not exposed.
• Encountered unknown AtomicType…

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

Appendix: 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)