{"record":{"id":"641fe04e0f70072c","repo":"apache/beam","slug":"could-not-resolve-table-in-data-catalog-tablename","errorCode":null,"errorMessage":"Could not resolve table in Data Catalog: {tableName}","messagePattern":"Could not resolve table in Data Catalog: (.+?)","errorType":"exception","errorClass":"InvalidTableException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/datacatalog/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/datacatalog/DataCatalogTableProvider.java","lineNumber":151,"sourceCode":"    return tableProvider.buildBeamSqlTable(table);\n  }\n\n  private Table loadTable(String tableName) {\n    if (!tableCache.containsKey(tableName)) {\n      tableCache.put(tableName, loadTableFromDC(tableName));\n    }\n\n    return tableCache.get(tableName);\n  }\n\n  private Table loadTableFromDC(String tableName) {\n    try {\n      return toCalciteTable(\n          tableName,\n          dataCatalog.lookupEntry(\n              LookupEntryRequest.newBuilder().setSqlResource(tableName).build()));\n    } catch (InvalidArgumentException | PermissionDeniedException | NotFoundException e) {\n      throw new InvalidTableException(\"Could not resolve table in Data Catalog: \" + tableName, e);\n    }\n  }\n\n  @Internal\n  public static DataCatalogClient createDataCatalogClient(DataCatalogPipelineOptions options) {\n    try {\n      DataCatalogSettings.Builder builder =\n          DataCatalogSettings.newBuilder()\n              .setCredentialsProvider(() -> options.as(GcpOptions.class).getGcpCredential())\n              .setEndpoint(options.getDataCatalogEndpoint());\n\n      // Retry permission denied errors, they are likely due to sync delay.\n      // Limit max retry delay to 1 minute, at that point its probably a legitimate permission error\n      // and we should get back to the user.\n      builder\n          .lookupEntrySettings()\n          .setRetryableCodes(\n              ImmutableSet.of(Code.PERMISSION_DENIED, Code.DEADLINE_EXCEEDED, Code.UNAVAILABLE))","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/datacatalog/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/datacatalog/DataCatalogTableProvider.java#L133-L169","documentation":"When resolving a table name through DataCatalog's lookupEntry, the provider converts API errors (invalid argument, permission denied, not found) into Beam's InvalidTableException with the message \"Could not resolve table in Data Catalog: <tableName>\". The original GCP exception is attached as the cause.","triggerScenarios":"Calling getTable/loadTable with a tableName that (a) does not exist in DataCatalog, (b) the caller lacks permission to view, or (c) is not a valid SQL resource name (expected format like project.dataset.table or project:dataset.table).","commonSituations":"Typos in table names, missing IAM roles (datacatalog.viewer) on the project, querying tables from a different GCP project than the credentials can see, or using the wrong fully-qualified name format.","solutions":["Verify the table exists in DataCatalog and the name matches the expected SQL resource format (project[.:]dataset.table).","Grant the caller IAM permission to look up the entry (roles/datacatalog.viewer or stronger).","Check credentials/application default credentials point to the right project and inspect the cause exception for which of the three GCP errors fired."],"exampleFix":"// before\nTable t = provider.getTable(\"my_ds.my_table\"); // unqualified name\n\n// after\nTable t = provider.getTable(\"my-proj.my_ds.my_table\"); // fully qualified","handlingStrategy":"try-catch","validationCode":"if (!name.matches(\"^([a-zA-Z0-9-_]+)[.:][a-zA-Z0-9-_]+[.:][a-zA-Z0-9-_]+$\")) {\n  throw new IllegalArgumentException(\"Use fully-qualified project.dataset.table name\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  Table t = provider.getTable(name);\n} catch (InvalidTableException e) {\n  // inspect e.getCause(): NotFoundException | PermissionDeniedException | InvalidArgumentException\n}","preventionTips":["Use fully-qualified project[.:]dataset.table names","Grant roles/datacatalog.viewer to the pipeline's service account","Confirm the entry exists in the target GCP project before querying"],"tags":["apache-beam","datacatalog","java","gcp"],"backgroundTag":"record-not-found","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"}