{"record":{"id":"098351f1f751426d","repo":"apache/beam","slug":"instanceid-can-t-be-empty","errorCode":null,"errorMessage":"instanceId can't be empty","messagePattern":"instanceId can't be empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/SpannerTransformRegistrar.java","lineNumber":131,"sourceCode":"    }\n\n    public void setClientCertPath(@Nullable String clientCertPath) {\n      this.clientCertPath = clientCertPath;\n    }\n\n    public void setClientCertKeyPath(@Nullable String clientCertKeyPath) {\n      this.clientCertKeyPath = clientCertKeyPath;\n    }\n\n    void checkMandatoryFields() {\n      if (projectId.isEmpty()) {\n        throw new IllegalArgumentException(\"projectId can't be empty\");\n      }\n      if (databaseId.isEmpty()) {\n        throw new IllegalArgumentException(\"databaseId can't be empty\");\n      }\n      if (instanceId.isEmpty()) {\n        throw new IllegalArgumentException(\"instanceId can't be empty\");\n      }\n      if ((clientCertPath != null) != (clientCertKeyPath != null)) {\n        throw new IllegalArgumentException(\n            \"Both clientCertPath and clientCertKeyPath must be specified together.\");\n      }\n    }\n  }\n\n  public static class ReadBuilder\n      implements ExternalTransformBuilder<ReadBuilder.Configuration, PBegin, PCollection<Row>> {\n\n    public static class Configuration extends CrossLanguageConfiguration {\n      // TODO: https://github.com/apache/beam/issues/20415 Come up with something to determine\n      // schema without this explicit parameter\n      private Schema schema = Schema.builder().build();\n      private @Nullable String sql;\n      private @Nullable String table;\n      private @Nullable Boolean batching;","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/SpannerTransformRegistrar.java#L113-L149","documentation":"checkMandatoryFields() in SpannerTransformRegistrar enforces that an instanceId is provided alongside projectId and databaseId. A Cloud Spanner resource path is projects/<p>/instances/<i>/databases/<d>; without instanceId the client cannot build it, so the library throws IllegalArgumentException early. It indicates the Spanner builder was constructed incompletely.","triggerScenarios":"Calling SpannerIO.read()/write() or the external ChangeStreamReader/ReadBuilder configuration without withInstanceId(...), or with instanceId(\"\") — e.g. when the instance name is injected from a blank config value.","commonSituations":"Pipeline options where --spannerInstance was not passed on the command line; copy-pasted code where instanceId line was deleted; configs targeting Cloud Spanner emulator where the instance field was assumed optional.","solutions":["Add .withInstanceId(\"<your-instance>\") to the Spanner builder.","If derived from options, default it correctly or fail with a clear message before building the transform.","Confirm the instance name with `gcloud spanner instances list`."],"exampleFix":"// before\nSpannerIO.read().withProjectId(\"p\").withDatabaseId(\"db\")\n// after\nSpannerIO.read().withProjectId(\"p\").withInstanceId(\"i\").withDatabaseId(\"db\")","handlingStrategy":"validation","validationCode":"if (instanceId == null || instanceId.isEmpty()) { throw new IllegalArgumentException(\"instanceId must be set before building the Spanner transform\"); }","typeGuard":null,"tryCatchPattern":"try { return SpannerIO.read().withInstanceId(instanceId).withDatabaseId(db).withProjectId(p); } catch (IllegalArgumentException e) { throw new PipelineConfigException(\"Missing Spanner instanceId\", e); }","preventionTips":["Centralize Spanner config resolution in one factory that asserts all three identifiers.","Document required CLI/pipeline options and add a --dry-run config check.","Verify instance names with gcloud spanner instances list during setup."],"tags":["java","apache-beam","google-cloud-spanner","validation"],"backgroundTag":"empty-required-field","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}