{"record":{"id":"a425bbcfa00adfc1","repo":"apache/beam","slug":"exception-while-trying-to-retrieve-schema-a425bb","errorCode":null,"errorMessage":"Exception while trying to retrieve schema","messagePattern":"Exception while trying to retrieve schema","errorType":"exception","errorClass":"SpannerSchemaRetrievalException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/SpannerQuerySourceDef.java","lineNumber":52,"sourceCode":"  }\n\n  private SpannerQuerySourceDef(SpannerConfig config, Statement query) {\n    this.config = config;\n    this.query = query;\n  }\n\n  /** {@inheritDoc} */\n  @Override\n  public Schema getBeamSchema() {\n    Schema beamSchema;\n    try (SpannerAccessor spannerAccessor = SpannerAccessor.getOrCreate(config)) {\n      try (ReadContext readContext = spannerAccessor.getDatabaseClient().singleUse()) {\n        ResultSet result = readContext.analyzeQuery(query, ReadContext.QueryAnalyzeMode.PLAN);\n        result.next();\n        beamSchema = structTypeToBeamRowSchema(result.getMetadata().getRowType(), true);\n      }\n    } catch (Exception e) {\n      throw new SpannerSchemaRetrievalException(\"Exception while trying to retrieve schema\", e);\n    }\n    return beamSchema;\n  }\n}\n","sourceCodeStart":34,"sourceCodeEnd":57,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/SpannerQuerySourceDef.java#L34-L57","documentation":"SpannerQuerySourceDef.getBeamSchema() analyzes the query with QueryAnalyzeMode.PLAN to derive a Beam schema; any exception during that round trip is wrapped in SpannerSchemaRetrievalException(\"Exception while trying to retrieve schema\", e). The cause (Spanner API error, bad SQL, permissions) is attached as the cause.","triggerScenarios":"Calling getBeamSchema() (e.g., during SqlTransform resolution on a Spanner query source) when the single-use ReadContext analyzeQuery(PLAN) call fails: invalid SQL, missing Spanner permissions, network/API errors, or an empty/invalid query result metadata.","commonSituations":"SQL syntax/typing errors that break query planning; service account lacking spanner.databasees.read; transient Spanner unavailability; querying a database that no longer exists; Beam SQL join against a Spanner table whose schema can't be inferred.","solutions":["Inspect the cause chain of SpannerSchemaRetrievalException for the underlying SpannerException.","Run the SQL directly in the Spanner console / gcloud to reproduce the planning error.","Verify IAM permissions (spanner.databases.read, and read metadata) for the credentials in SpannerConfig.","Check network/connectivity and Spanner service status; retry on transient errors."],"exampleFix":"// before\nPCollection<Row> rows = p.apply(SqlTransform.query(\"SELEC * FROM users\"));\n// after\nPCollection<Row> rows = p.apply(SqlTransform.query(\"SELECT * FROM users\"));","handlingStrategy":"try-catch","validationCode":"// Pre-flight: validate SQL and permissions by running a cheap PLAN analysis yourself\ntry (ReadContext ctx = dbClient.singleUse()) { ctx.analyzeQuery(sql, ReadContext.QueryAnalyzeMode.PLAN); }","typeGuard":null,"tryCatchPattern":"try { rows = p.apply(SqlTransform.query(sql)); } catch (SpannerSchemaRetrievalException e) { LOG.error(\"Schema retrieval failed\", e.getCause()); throw new RuntimeException(\"Fix SQL/permissions for: \" + sql, e); }","preventionTips":["Test the query in the Spanner console before wiring it into Beam SQL.","Grant spanner.databases.read to the pipeline's service account.","Always inspect getCause() of SpannerSchemaRetrievalException."],"tags":["java","beam","spanner","schema","sql"],"backgroundTag":"schema-validation-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}