{"record":{"id":"004d70371b466595","repo":"apache/beam","slug":"metadatadatabase-can-t-be-empty","errorCode":null,"errorMessage":"MetadataDatabase can't be empty","messagePattern":"MetadataDatabase 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":507,"sourceCode":"    }\n\n    @Override\n    @NonNull\n    public PTransform<PBegin, PCollection<String>> buildExternal(\n        ChangeStreamReaderBuilder.Configuration configuration) {\n\n      configuration.checkMandatoryFields();\n\n      if (configuration.changeStreamName.isEmpty()) {\n        throw new IllegalArgumentException(\"ChangeStreamName can't be empty\");\n      }\n\n      if (configuration.metadataInstance.isEmpty()) {\n        throw new IllegalArgumentException(\"MetadataInstance can't be empty\");\n      }\n\n      if (configuration.metadataDatabase.isEmpty()) {\n        throw new IllegalArgumentException(\"MetadataDatabase can't be empty\");\n      }\n\n      SpannerIO.ReadChangeStream readChangeStream =\n          SpannerIO.readChangeStream()\n              .withProjectId(configuration.projectId)\n              .withInstanceId(configuration.instanceId)\n              .withDatabaseId(configuration.databaseId)\n              .withChangeStreamName(configuration.changeStreamName)\n              .withMetadataInstance(configuration.metadataInstance)\n              .withMetadataDatabase(configuration.metadataDatabase);\n\n      if (configuration.inclusiveStartAt != null) {\n        readChangeStream = readChangeStream.withInclusiveStartAt(configuration.inclusiveStartAt);\n      }\n\n      if (configuration.inclusiveEndAt != null) {\n        readChangeStream = readChangeStream.withInclusiveEndAt(configuration.inclusiveEndAt);\n      }","sourceCodeStart":489,"sourceCodeEnd":525,"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#L489-L525","documentation":"Thrown by ChangeStreamReaderBuilder.build() when the metadataDatabase configuration is empty. The connector requires a database in the metadata instance to persist change-stream connector metadata; without it the built transform cannot run.","triggerScenarios":"Building a SpannerIO.ReadChangeStream transform with withMetadataDatabase(\"\") omitted/left blank in the ChangeStreamReadConfiguration, then calling build().","commonSituations":"Pipeline options files missing the metadataDatabase key; users assuming the metadata database defaults to the source database but leaving the field empty; template parameters not bound at runtime.","solutions":["Set withMetadataDatabase(\"your-database\") (or populate the metadataDatabase option) with an existing Spanner database in the metadata instance.","Create the metadata database if it does not exist, or point at the database that hosts the change stream.","Add startup validation of the pipeline options to fail fast with a clear message."],"exampleFix":"// before\n.withMetadataInstance(metadataInstance)\n.withMetadataDatabase(\"\")\n// after\n.withMetadataInstance(metadataInstance)\n.withMetadataDatabase(\"metadata-db\")","handlingStrategy":"validation","validationCode":"// before building\nif (metadataDatabase == null || metadataDatabase.isEmpty()) {\n  throw new IllegalArgumentException(\"metadataDatabase must be a non-empty Spanner database ID\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set withMetadataDatabase explicitly; never rely on an implicit default.","Ensure the database exists in the metadata instance before launching the pipeline.","Add a config-lint step in CI for pipeline option files."],"tags":["spanner","configuration","change-stream","java"],"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-14T21:17:11.552Z"}