{"record":{"id":"c38977794b103546","repo":"apache/beam","slug":"gcsutil-v2-not-initialized","errorCode":null,"errorMessage":"GcsUtil V2 not initialized.","messagePattern":"GcsUtil V2 not initialized\\.","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/GcsUtil.java","lineNumber":139,"sourceCode":"    if (delegateV2 != null) {\n      return delegateV2.fileSize(path);\n    }\n    return delegate.fileSize(path);\n  }\n\n  /**\n   * @deprecated use {@link #getBlob(GcsPath, BlobGetOption...)}.\n   */\n  @Deprecated\n  public StorageObject getObject(GcsPath gcsPath) throws IOException {\n    return delegate.getObject(gcsPath);\n  }\n\n  public Blob getBlob(GcsPath gcsPath, BlobGetOption... options) throws IOException {\n    if (delegateV2 != null) {\n      return delegateV2.getBlob(gcsPath, options);\n    }\n    throw new IOException(\"GcsUtil V2 not initialized.\");\n  }\n\n  /**\n   * @deprecated use {@link #getBlobs(Iterable, BlobGetOption...)}.\n   */\n  @Deprecated\n  public List<StorageObjectOrIOException> getObjects(List<GcsPath> gcsPaths) throws IOException {\n    List<GcsUtilV1.StorageObjectOrIOException> legacy = delegate.getObjects(gcsPaths);\n    return legacy.stream()\n        .map(StorageObjectOrIOException::fromLegacy)\n        .collect(java.util.stream.Collectors.toList());\n  }\n\n  public List<BlobResult> getBlobs(Iterable<GcsPath> gcsPaths, BlobGetOption... options)\n      throws IOException {\n    if (delegateV2 != null) {\n      return delegateV2.getBlobs(gcsPaths, options);\n    }","sourceCodeStart":121,"sourceCodeEnd":157,"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/GcsUtil.java#L121-L157","documentation":"GcsUtil delegates Blob-API (GCS JSON API v2) calls to delegateV2. getBlob throws IOException('GcsUtil V2 not initialized.') when the v2 delegate was never constructed — i.e. the GcsUtil was built via the legacy path without GCS v2 storage support enabled.","triggerScenarios":"Calling gcsUtil.getBlob(gcsPath, options) on a GcsUtil instance whose delegateV2 is null (constructed in legacy/test mode without v2 initialization).","commonSituations":"Tests constructing GcsUtil with a mocked legacy GcsUtil object; older integration paths that never call the v2 initializer; code using getBlob directly instead of the legacy object()/objectMetadata() methods.","solutions":["Use the legacy GcsUtil.object()/objectMetadata() methods which do not require the v2 delegate","Initialize GcsUtil with the v2 delegate (enable GCS v2 storage support in options) before calling getBlob","Check Beam version requirements/flags for GoogleCloudOptions experimental GCS v2 support","If mocking in tests, also stub the v2 delegate or avoid exercising getBlob"],"exampleFix":"// before\nBlob blob = gcsUtil.getBlob(gcsPath);\n// after\nGcsUtil.GcsUtilFactory factory = new GcsUtil.GcsUtilFactory();\nGcsUtil gcsUtil = factory.create(pipelineOptions); // initializes v2 delegate\nBlob blob = gcsUtil.getBlob(gcsPath);","handlingStrategy":"try-catch","validationCode":"// check availability before calling\ntry { gcsUtil.getBlob(gcsPath); } catch (IOException e) { /* handle not-initialized vs real IO error */ }","typeGuard":null,"tryCatchPattern":"try { Blob b = gcsUtil.getBlob(gcsPath); }\ncatch (IOException e) {\n  if (\"GcsUtil V2 not initialized.\".equals(e.getMessage())) {\n    throw new IllegalStateException(\"Rebuild GcsUtil via GcsUtilFactory with v2 support\", e);\n  }\n  throw e;\n}","preventionTips":["Construct GcsUtil through GcsUtil.GcsUtilFactory, not the legacy no-arg/mock constructor","Prefer legacy object()/objectMetadata() methods when v2 support is not needed","Add a test asserting v2-dependent paths use a factory-built GcsUtil"],"tags":["gcs","initialization","gcs-util","java"],"backgroundTag":"internal-invariant-violation","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"}