{"record":{"id":"c5e38ee4736232c9","repo":"apache/beam","slug":"error-matching-file-spec-s-status-s","errorCode":null,"errorMessage":"Error matching file spec %s: status %s","messagePattern":"Error matching file spec (.+?): status (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileSystems.java","lineNumber":198,"sourceCode":"  }\n\n  /**\n   * Returns the {@link Metadata} for a single file resource. Expects a resource specification\n   * {@code spec} that matches a single result.\n   *\n   * @param spec a resource specification that matches exactly one result.\n   * @return the {@link Metadata} for the specified resource.\n   * @throws FileNotFoundException if the file resource is not found.\n   * @throws IOException in the event of an error in the inner call to {@link #match}, or if the\n   *     given spec does not match exactly 1 result.\n   */\n  public static Metadata matchSingleFileSpec(String spec) throws IOException {\n    List<MatchResult> matches = FileSystems.match(Collections.singletonList(spec));\n    MatchResult matchResult = Iterables.getOnlyElement(matches);\n    if (matchResult.status() == Status.NOT_FOUND) {\n      throw new FileNotFoundException(String.format(\"File spec %s not found\", spec));\n    } else if (matchResult.status() != Status.OK) {\n      throw new IOException(\n          String.format(\"Error matching file spec %s: status %s\", spec, matchResult.status()));\n    } else {\n      List<Metadata> metadata = matchResult.metadata();\n      if (metadata.size() != 1) {\n        throw new IOException(\n            String.format(\n                \"Expecting spec %s to match exactly one file, but matched %s: %s\",\n                spec, metadata.size(), metadata));\n      }\n      return metadata.get(0);\n    }\n  }\n\n  /**\n   * Returns {@link MatchResult MatchResults} for the given {@link ResourceId resourceIds}.\n   *\n   * @param resourceIds {@link ResourceId resourceIds} that might be derived from {@link #match},\n   *     {@link ResourceId#resolve}, or {@link ResourceId#getCurrentDirectory()}.","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/io/FileSystems.java#L180-L216","documentation":"FileSystems.matchSingleFileSpec throws IOException when the underlying MatchResult status is neither OK nor NOT_FOUND, meaning the filesystem provider could not determine match results (e.g. an error occurred listing/matching).","triggerScenarios":"Calling FileSystems.matchSingleFileSpec when the filesystem backend returns MatchResult.Status.ERROR — e.g. GCS/S3 listing failures, permission issues surfaced by the provider, or transient network errors during match.","commonSituations":"GCS API throttling or transient 5xx during match; IAM/service-account permission failures on bucket listing; HDFS NameNode unavailability.","solutions":["Retry the match with exponential backoff for transient backend errors","Check filesystem credentials and permissions for the path's scheme","Log matchResult.status() to identify the provider-specific failure","Inspect the provider's logs (GCS client, HDFS client) for the root cause"],"exampleFix":"// before\nMetadata md = FileSystems.matchSingleFileSpec(spec); // throws raw IOException\n// after\ntry {\n  Metadata md = FileSystems.matchSingleFileSpec(spec);\n} catch (IOException e) {\n  LOG.warn(\"Transient match failure for %s, retrying\", spec, e);\n  Metadata md = retryWithBackoff(() -> FileSystems.matchSingleFileSpec(spec));\n}","handlingStrategy":"retry","validationCode":"// Check permissions/reachability of the scheme before matching\ndryRunMatch(spec); // custom pre-check with limited retries and clear error reporting","typeGuard":null,"tryCatchPattern":"try {\n  return FileSystems.matchSingleFileSpec(spec);\n} catch (IOException e) {\n  if (attempt < MAX_RETRIES) return retryWithBackoff(spec, attempt + 1);\n  throw new IOException(\"Match failed after retries for \" + spec, e);\n}","preventionTips":["Configure retry with exponential backoff for cloud storage backends","Verify IAM/service-account permissions for listing","Monitor backend health (GCS status, HDFS NameNode) for transient outages","Wrap match calls in a helper that centralizes retry policy"],"tags":["java","apache-beam","filesystem","io","retry"],"backgroundTag":"http-request-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}