apache/beam · error · IOException

rethrown stored IOException (typically "MatchResult status…

Error message

rethrown stored IOException (typically "MatchResult status is UNKNOWN, and metadata is not available.")

What it means

MatchResult.Failure holds a stored IOException (typically 'MatchResult status is UNKNOWN, and metadata is not available'). Calling metadata() on a failed/unknown match result rethrows that stored exception instead of returning metadata. Callers must check status() before asking for metadata.

Solutions

Check matchResult.status() and handle Status.NOT_MATCH / FAILURE before calling metadata().
Retry the match operation (transient store failures are common).
Log/inspect getException() for the root cause (permissions, missing bucket, quota).

Example fix

// before
List<Metadata> md = matchResult.metadata();
// after
if (matchResult.status() == Status.OK) {
  List<Metadata> md = matchResult.metadata();
} else {
  // handle NOT_MATCH / retry for UNKNOWN
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check
if (matchResult.status() != MatchResult.Status.OK) {
  // do NOT call metadata(); handle NOT_MATCH or retry UNKNOWN
}

Try / catch

try {
  List<Metadata> md = matchResult.metadata();
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("UNKNOWN")) {
    // retry match with backoff
  } else {
    throw e;
  }
}

Prevention

Always branch on status() before metadata().
Retry matches with exponential backoff for cloud stores.
Log getException() to distinguish permission vs transient errors.

When it happens

Trigger: FileSystems.match/glob resolution failed or returned Status.UNKNOWN, and downstream code calls result.metadata() without checking status() first.

Common situations: GCS/S3 transient outages during file matching; listing inputs whose glob evaluation errored; code that assumes match() always returns NO_MATCH or metadata and never a FAILURE result.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/io/fs/MatchResult.java:59

    @Override
    public List<Metadata> metadata() throws IOException {
      return getMetadata();
    }
  }

  /** Returns a {@link MatchResult} given the {@link Status} and {@link IOException}. */
  public static MatchResult create(final Status status, final IOException e) {
    return new AutoValue_MatchResult_Failure(status, e);
  }

  @AutoValue
  abstract static class Failure extends MatchResult {
    abstract IOException getException();

    @Override
    public List<Metadata> metadata() throws IOException {
      throw getException();
    }
  }

  /** Returns a {@link MatchResult} with {@link Status#UNKNOWN}. */
  public static MatchResult unknown() {
    return new AutoValue_MatchResult_Failure(
        Status.UNKNOWN,
        new IOException("MatchResult status is UNKNOWN, and metadata is not available."));
  }

  /** Status of the {@link MatchResult}. */
  public abstract Status status();

  /**
   * {@link Metadata} of matched files. Note that if {@link #status()} is {@link Status#NOT_FOUND},
   * this may either throw a {@link java.io.FileNotFoundException} or return an empty list,
   * depending on the {@link EmptyMatchTreatment} used in the {@link FileSystems#match} call.
   */

View on GitHub (pinned to 12126d8942)