{"record":{"id":"d9dc31e2e7ad5aec","repo":"apache/beam","slug":"unable-to-subscribe-to-subscriptionpath","errorCode":null,"errorMessage":"Unable to subscribe to ${subscriptionPath}: ","messagePattern":"Unable to subscribe to (.+?): ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/pubsub/PubsubUnboundedSource.java","lineNumber":1112,"sourceCode":"          subscriptionPath == null ? null : subscriptionPath.get();\n      if (subscriptionPathVal == null) {\n        if (checkpoint == null) {\n          // This reader has never been started and there was no call to #split;\n          // create a single random subscription, which will be kept in the checkpoint.\n          subscription = outer.createRandomSubscription(options);\n        } else {\n          subscription =\n              checkStateNotNull(\n                  checkpoint.getSubscription(),\n                  \"Checkpoint must have a subscription path when subscriptionPath is not set.\");\n        }\n      } else {\n        subscription = subscriptionPathVal;\n      }\n      try {\n        reader = new PubsubReader(options.as(PubsubOptions.class), this, subscription);\n      } catch (GeneralSecurityException | IOException e) {\n        throw new RuntimeException(\"Unable to subscribe to \" + subscriptionPath + \": \", e);\n      }\n      if (checkpoint != null) {\n        // NACK all messages we may have lost.\n        try {\n          // Will BLOCK until NACKed.\n          checkpoint.nackAll(reader);\n        } catch (IOException e) {\n          LOG.error(\n              \"Pubsub {} cannot have {} lost messages NACKed, ignoring exception.\",\n              subscriptionPath,\n              checkpoint.notYetReadIds.size(),\n              e);\n        }\n      }\n      return reader;\n    }\n\n    @Override","sourceCodeStart":1094,"sourceCodeEnd":1130,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/pubsub/PubsubUnboundedSource.java#L1094-L1130","documentation":"PubsubUnboundedSource.read() wraps GeneralSecurityException or IOException thrown while constructing PubsubReader (opening the Pubsub client and subscribing) into RuntimeException(\"Unable to subscribe to <subscriptionPath>: \", e). It means the pipeline failed to establish a subscription to the given Pubsub subscription at startup. The chained cause holds the real reason (auth, network, quota, missing subscription).","triggerScenarios":"Starting a streaming pipeline whose PubsubIO.read().subscription(...) path cannot be opened: invalid credentials, unreachable Pubsub endpoint (custom rootUrl/firewall), or the subscription does not exist / was deleted.","commonSituations":"Missing or expired GOOGLE_APPLICATION_CREDENTIALS in Dataflow/worker env; typo in subscription path or wrong project; subscription auto-created earlier was garbage-collected; proxy or private-network blocking pubsub.googleapis.com.","solutions":["Read the caused-by chain to identify the real failure (security vs IO) and fix accordingly.","Verify the subscription exists: gcloud pubsub subscriptions describe <subscription>.","Check credentials: ensure Application Default Credentials are valid in the runtime environment.","If using a custom Pubsub root URL, confirm network/proxy reachability from workers.","Recreate the subscription if it was deleted before the pipeline start."],"exampleFix":"// before\noptions.setGoogleApplicationCredentialsPath(\"/stale/path/key.json\");\n// after (verify before submitting)\n// gcloud pubsub subscriptions describe projects/p/subscriptions/s\n// export GOOGLE_APPLICATION_CREDENTIALS=/valid/path/key.json\npipeline.apply(\"ReadPubsub\", PubsubIO.readMessages().fromSubscription(subscriptionPath));","handlingStrategy":"retry","validationCode":"gcloud pubsub subscriptions describe <path>  # run before submitting the pipeline\ngcloud auth application-default print-access-token  # verify credentials","typeGuard":"null","tryCatchPattern":"try { pipeline.run().waitUntilFinish(); } catch (RuntimeException e) { Throwable c = e.getCause(); if (c instanceof IOException) { /* check network/endpoint */ } else if (c instanceof GeneralSecurityException) { /* fix credentials */ } }","preventionTips":["Validate subscription existence and credentials before pipeline launch.","Use fromSubscription with a pre-provisioned subscription for production.","Test endpoint reachability (pubsub.googleapis.com or custom rootUrl) from worker network."],"tags":["java","pubsub","network","authentication"],"backgroundTag":"subscription-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"}