{"record":{"id":"ade56932994c9a77","repo":"apache/iceberg","slug":"registering-tables-with-overwrite-is-not-supported","errorCode":null,"errorMessage":"Registering tables with overwrite is not supported","messagePattern":"Registering tables with overwrite is not supported","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/org/apache/iceberg/catalog/Catalog.java","lineNumber":382,"sourceCode":"  }\n\n  /**\n   * Register a table with the catalog.\n   *\n   * @param identifier a table identifier\n   * @param metadataFileLocation the location of a metadata file\n   * @param overwrite whether to overwrite an existing table registration\n   * @return a Table instance\n   * @throws AlreadyExistsException if {@code overwrite} is false and the table already exists in\n   *     the catalog\n   */\n  default Table registerTable(\n      TableIdentifier identifier, String metadataFileLocation, boolean overwrite) {\n    if (!overwrite) {\n      return registerTable(identifier, metadataFileLocation);\n    }\n\n    throw new UnsupportedOperationException(\"Registering tables with overwrite is not supported\");\n  }\n\n  /**\n   * Instantiate a builder to either create a table or start a create/replace transaction.\n   *\n   * @param identifier a table identifier\n   * @param schema a schema\n   * @return the builder to create a table or start a create/replace transaction\n   */\n  default TableBuilder buildTable(TableIdentifier identifier, Schema schema) {\n    throw new UnsupportedOperationException(\n        this.getClass().getName() + \" does not implement buildTable\");\n  }\n\n  /**\n   * Initialize a catalog given a custom name and a map of catalog properties.\n   *\n   * <p>A custom Catalog implementation must have a no-arg constructor. A compute engine like Spark","sourceCodeStart":364,"sourceCodeEnd":400,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/api/src/main/java/org/apache/iceberg/catalog/Catalog.java#L364-L400","documentation":"Catalog.registerTable(identifier, metadataFileLocation, overwrite) throws UnsupportedOperationException when overwrite=true, unless the catalog implementation overrides it. Only the non-overwrite path is delegated to the two-argument registerTable default. The default method exists so catalogs can opt in to overwrite registration; most do not.","triggerScenarios":"Calling the three-argument registerTable with overwrite=true on a Catalog that only overrides (or does not implement) the two-argument version.","commonSituations":"Re-registering a table over an existing entry during repair/migration scripts; force-swapping a table's metadata pointer after a botched operation; using a generic catalog reference whose backend doesn't allow overwrite.","solutions":["Call the two-argument registerTable(identifier, metadataFileLocation) instead, after dropping the existing table if replacement is intended","Upgrade to a catalog implementation that overrides the overwrite variant","Implement the three-argument registerTable in the custom catalog","If the table already exists, drop it first then re-register without overwrite"],"exampleFix":"// before\ncatalog.registerTable(ident, metadataFileLocation, true);\n// after\ncatalog.dropTable(ident);\ncatalog.registerTable(ident, metadataFileLocation);","handlingStrategy":"try-catch","validationCode":"if (overwrite && !catalogOverwriteSupported) {\n  // fall back to drop + register\n}","typeGuard":null,"tryCatchPattern":"try {\n  catalog.registerTable(ident, metadataFileLocation, true);\n} catch (UnsupportedOperationException e) {\n  catalog.dropTable(ident);\n  catalog.registerTable(ident, metadataFileLocation);\n}","preventionTips":["Default to overwrite=false unless explicitly needed","Model overwrite as drop-then-register in portable code","Confirm backend capability before exposing overwrite flags in tooling","Document catalog-specific limitations in migration runbooks"],"tags":["java","unsupported-operation","catalog","overwrite"],"backgroundTag":"unsupported-operation","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}