{"record":{"id":"6e694d060214be41","repo":"apache/beam","slug":"exception-while-trying-to-retrieve-schema-6e694d","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/SpannerTableSourceDef.java","lineNumber":59,"sourceCode":"    this.config = config;\n    this.columns = columns;\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.read(table, KeySet.all(), columns, Options.limit(1));\n        if (result.next()) {\n          beamSchema = structTypeToBeamRowSchema(result.getMetadata().getRowType(), true);\n        } else {\n          throw new SpannerSchemaRetrievalException(\"Cannot find Spanner table.\");\n        }\n      }\n    } catch (Exception e) {\n      throw new SpannerSchemaRetrievalException(\"Exception while trying to retrieve schema\", e);\n    }\n    return beamSchema;\n  }\n}\n","sourceCodeStart":41,"sourceCodeEnd":64,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/SpannerTableSourceDef.java#L41-L64","documentation":"The outer catch-all of SpannerTableSourceDef.getBeamSchema() wraps any Exception thrown while reading the table or building the Beam schema into SpannerSchemaRetrievalException(\"Exception while trying to retrieve schema\", e). This includes Spanner API errors (NOT_FOUND, PERMISSION_DENIED, DEADLINE_EXCEEDED), session errors, and mapping failures — the real cause is on the exception's cause chain.","triggerScenarios":"Any failure during getBeamSchema() other than the explicit empty-result case: nonexistent table (SpannerException NOT_FOUND), insufficient IAM permissions, transient Spanner unavailability, timeouts, or structTypeToBeamRowSchema mapping errors.","commonSituations":"Wrong instance/database/table name in SpannerConfig; service account without spanner.databases.read; Spanner incident or network partition; unsupported column types failing schema mapping.","solutions":["Log/inspect the cause of SpannerSchemaRetrievalException for the concrete SpannerException code.","Fix SpannerConfig (projectId/instanceId/databaseId/table name) to match an existing table.","Grant the caller spanner.databases.read (and related) IAM roles.","Retry on transient codes (DEADLINE_EXCEEDED, UNAVAILABLE); check Google Cloud status if persistent."],"exampleFix":"// before\nPCollection<Row> rows = p.apply(SpannerRead.of(wrongConfig).withTable(\"users\"));\n// after\nSpannerConfig cfg = SpannerConfig.create().withProjectId(\"my-project\").withInstanceId(\"prod\").withDatabaseId(\"app\");\nPCollection<Row> rows = p.apply(SpannerRead.of(cfg).withTable(\"users\"));","handlingStrategy":"try-catch","validationCode":"// Pre-flight existence + permission probe\ntry (ResultSet rs = dbClient.singleUse().executeQuery(Statement.of(\"SELECT 1 FROM \" + table + \" LIMIT 1\"))) { rs.next(); }","typeGuard":null,"tryCatchPattern":"try { rows = p.apply(SpannerRead.of(config).withTable(table)); } catch (SpannerSchemaRetrievalException e) {\n  Throwable cause = e.getCause();\n  if (cause instanceof SpannerException) { switch (((SpannerException) cause).getErrorCode()) { case NOT_FOUND: /* fix config */ break; case PERMISSION_DENIED: /* fix IAM */ break; case UNAVAILABLE: case DEADLINE_EXCEEDED: /* retry */ break; default: throw e; } } else throw e;\n}","preventionTips":["Log the full cause chain, not just the wrapper message.","Grant spanner.databases.read to the pipeline service account.","Validate SpannerConfig coordinates before submitting the job.","Add retries for transient Spanner error codes."],"tags":["java","beam","spanner","schema","api-error"],"backgroundTag":"database-query-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"}