{"record":{"id":"641a6ec494c6f614","repo":"apache/beam","slug":"rethrown-stored-ioexception-typically-matchresult-status-is","errorCode":null,"errorMessage":"rethrown stored IOException (typically \"MatchResult status is UNKNOWN, and metadata is not available.\")","messagePattern":"rethrown stored IOException \\(typically \"MatchResult status is UNKNOWN, and metadata is not available\\.\"\\)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/io/fs/MatchResult.java","lineNumber":59,"sourceCode":"\n    @Override\n    public List<Metadata> metadata() throws IOException {\n      return getMetadata();\n    }\n  }\n\n  /** Returns a {@link MatchResult} given the {@link Status} and {@link IOException}. */\n  public static MatchResult create(final Status status, final IOException e) {\n    return new AutoValue_MatchResult_Failure(status, e);\n  }\n\n  @AutoValue\n  abstract static class Failure extends MatchResult {\n    abstract IOException getException();\n\n    @Override\n    public List<Metadata> metadata() throws IOException {\n      throw getException();\n    }\n  }\n\n  /** Returns a {@link MatchResult} with {@link Status#UNKNOWN}. */\n  public static MatchResult unknown() {\n    return new AutoValue_MatchResult_Failure(\n        Status.UNKNOWN,\n        new IOException(\"MatchResult status is UNKNOWN, and metadata is not available.\"));\n  }\n\n  /** Status of the {@link MatchResult}. */\n  public abstract Status status();\n\n  /**\n   * {@link Metadata} of matched files. Note that if {@link #status()} is {@link Status#NOT_FOUND},\n   * this may either throw a {@link java.io.FileNotFoundException} or return an empty list,\n   * depending on the {@link EmptyMatchTreatment} used in the {@link FileSystems#match} call.\n   */","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/io/fs/MatchResult.java#L41-L77","documentation":"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.","triggerScenarios":"FileSystems.match/glob resolution failed or returned Status.UNKNOWN, and downstream code calls result.metadata() without checking status() first.","commonSituations":"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.","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)."],"exampleFix":"// before\nList<Metadata> md = matchResult.metadata();\n// after\nif (matchResult.status() == Status.OK) {\n  List<Metadata> md = matchResult.metadata();\n} else {\n  // handle NOT_MATCH / retry for UNKNOWN\n}","handlingStrategy":"try-catch","validationCode":"// pre-check\nif (matchResult.status() != MatchResult.Status.OK) {\n  // do NOT call metadata(); handle NOT_MATCH or retry UNKNOWN\n}","typeGuard":null,"tryCatchPattern":"try {\n  List<Metadata> md = matchResult.metadata();\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"UNKNOWN\")) {\n    // retry match with backoff\n  } else {\n    throw e;\n  }\n}","preventionTips":["Always branch on status() before metadata().","Retry matches with exponential backoff for cloud stores.","Log getException() to distinguish permission vs transient errors."],"tags":["java","filesystem","io","matchresult","beam-io"],"backgroundTag":"file-read-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}