references/catalog/gotchas.md
Basin Catalog Troubleshooting
Identify whether the failure occurs in catalog administration, engine metadata access, or underlying object access before changing permissions or client settings.
| Check | Documentation | |-------|---------------| | Catalog enablement, Catalog URI, or Warehouse mismatch | Manage catalogs | | Reader/writer token scope or file-access denial | Engine authentication — inspect both catalog and storage permissions | | Missing maintenance credentials or wrong table/catalog configuration | Control-plane API and enable compaction | | Compaction backlog, retention, or orphaned files | Table maintenance | | PyIceberg connection or table creation | PyIceberg configuration | | Spark dependency, credential-vending, or signing configuration | PySpark configuration | | Deleted data is still present | Deleting data | | Catalog request or maintenance-job diagnosis | Metrics and analytics |
Compare the client's configured URI and warehouse with the actual catalog values. Test a read operation first; do not grant write access merely to resolve a reader's failure. For schema or concurrency errors, inspect the installed engine's behavior and current table metadata before retrying. The get-table note is not a substitute for verifying the service's response contract.
See configuration and patterns for implementation choices.