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.