{"record":{"id":"59634c051f511d90","repo":"apache/beam","slug":"unable-to-match-files-in-bucket-s-prefix-s","errorCode":null,"errorMessage":"Unable to match files in bucket %s, prefix %s.","messagePattern":"Unable to match files in bucket (.+?), prefix (.+?)\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/google-cloud-platform-core/src/main/java/org/apache/beam/sdk/extensions/gcp/util/GcsUtilV1.java","lineNumber":477,"sourceCode":"   */\n  public Objects listObjects(\n      String bucket, String prefix, @Nullable String pageToken, @Nullable String delimiter)\n      throws IOException {\n    // List all objects that start with the prefix (including objects in sub-directories).\n    Storage.Objects.List listObject = storageClient.objects().list(bucket);\n    listObject.setMaxResults(MAX_LIST_ITEMS_PER_CALL);\n    listObject.setPrefix(prefix);\n    listObject.setDelimiter(delimiter);\n\n    if (pageToken != null) {\n      listObject.setPageToken(pageToken);\n    }\n\n    try {\n      return ResilientOperation.retry(\n          listObject::execute, createBackOff(), RetryDeterminer.SOCKET_ERRORS, IOException.class);\n    } catch (Exception e) {\n      throw new IOException(\n          String.format(\"Unable to match files in bucket %s, prefix %s.\", bucket, prefix), e);\n    }\n  }\n\n  /**\n   * Returns the file size from GCS or throws {@link FileNotFoundException} if the resource does not\n   * exist.\n   */\n  @VisibleForTesting\n  List<Long> fileSizes(List<GcsPath> paths) throws IOException {\n    List<StorageObjectOrIOException> results = getObjects(paths);\n\n    ImmutableList.Builder<Long> ret = ImmutableList.builder();\n    for (StorageObjectOrIOException result : results) {\n      ret.add(toFileSize(result));\n    }\n    return ret.build();\n  }","sourceCodeStart":459,"sourceCodeEnd":495,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/google-cloud-platform-core/src/main/java/org/apache/beam/sdk/extensions/gcp/util/GcsUtilV1.java#L459-L495","documentation":"GcsUtilV1.listObjects wraps failures from the GCS Storage.objects.list call into this IOException when retries (ResilientOperation with SOCKET_ERRORS RetryDeterminer) are exhausted or a non-socket error occurs. It means the library could not enumerate objects under the given bucket/prefix. The underlying API exception is chained as the cause.","triggerScenarios":"Calling listObjects(bucket, prefix) when GCS list calls fail repeatedly with socket errors, when the bucket does not exist or is inaccessible (403/404 not retried), or when the list request is otherwise rejected.","commonSituations":"Listing a bucket that was deleted or renamed, missing storage.objects.list permission, transient network failures exhausting the backoff, or an invalid prefix.","solutions":["Inspect the chained cause for the actual GCS error status","Verify bucket exists and the caller has storage.objects.list permission","Confirm bucket name and prefix values","Increase/adjust the BackOff if transient socket errors are the cause"],"exampleFix":"// before\nList<GcsPath> files = gcsUtil.listObjects(bucket, prefix);\n// after\ntry {\n  List<GcsPath> files = gcsUtil.listObjects(bucket, prefix);\n} catch (IOException e) {\n  throw new IOException(\"Failed to list gs://\" + bucket + \"/\" + prefix + \": \" + e.getCause(), e);\n}","handlingStrategy":"try-catch","validationCode":"// pre-check bucket access\nboolean ok = gcsUtil.bucketExists(GcsPath.fromUri(\"gs://\" + bucket));","typeGuard":"boolean isListFailure(IOException e) { return e.getMessage() != null && e.getMessage().startsWith(\"Unable to match files\"); }","tryCatchPattern":"try {\n  files = gcsUtil.listObjects(bucket, prefix);\n} catch (IOException e) {\n  LOG.error(\"list failed for gs://{}/{}, cause={}\", bucket, prefix, e.getCause(), e);\n  throw e;\n}","preventionTips":["Verify bucket exists and list permission before enumerating","Use bounded prefixes to limit result size","Retry transient socket errors","Validate bucket naming rules"],"tags":["gcs","io","network"],"backgroundTag":"api-request-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-15T02:17:10.978Z"}