1# Gotchas & Troubleshooting
2 
3Common problems → causes → solutions.
4 
5## Permission Errors
6 
7### 401 Unauthorized
8 
9**Error:** `"401 Unauthorized"`  
10**Cause:** Token missing R2 Data Catalog permissions.  
11**Solution:** Use "Admin Read & Write" token (includes catalog + storage permissions). Test with `catalog.list_namespaces()`.
12 
13### 403 Forbidden
14 
15**Error:** `"403 Forbidden"` on data files  
16**Cause:** Token lacks storage permissions.  
17**Solution:** Token needs both R2 Data Catalog + R2 Storage Bucket Item permissions.
18 
19### Token Rotation Issues
20 
21**Error:** New token fails after rotation.  
22**Solution:** Create new token → test in staging → update prod → monitor 24h → revoke old.
23 
24## Catalog URI Issues
25 
26### 404 Not Found
27 
28**Error:** `"404 Catalog not found"`  
29**Cause:** Catalog not enabled or wrong URI.  
30**Solution:** Run `wrangler r2 bucket catalog enable <bucket>`. URI must be HTTPS with `/iceberg/` and case-sensitive bucket name.
31 
32### Wrong Warehouse
33 
34**Error:** Cannot create/load tables.  
35**Cause:** Warehouse ≠ bucket name.  
36**Solution:** Set `warehouse="bucket-name"` to match bucket exactly.
37 
38## Table and Schema Issues
39 
40### Table/Namespace Already Exists
41 
42**Error:** `"TableAlreadyExistsError"`  
43**Solution:** Use try/except to load existing or check first.
44 
45### Namespace Not Found
46 
47**Error:** Cannot create table.  
48**Solution:** Create namespace first: `catalog.create_namespace("ns")`
49 
50### Schema Evolution Errors
51 
52**Error:** `"422 Validation"` on schema update.  
53**Cause:** Incompatible change (required field, type shrink).  
54**Solution:** Only add nullable columns, compatible type widening (int→long, float→double).
55 
56## Data and Query Issues
57 
58### Empty Scan Results
59 
60**Error:** Scan returns no data.  
61**Cause:** Incorrect filter or partition column.  
62**Solution:** Test without filter first: `table.scan().to_pandas()`. Verify partition column names.
63 
64### Slow Queries
65 
66**Error:** Performance degrades over time.  
67**Cause:** Too many small files.  
68**Solution:** Check file count, compact if >1000 or avg <10MB. See [api.md](api.md#compaction).
69 
70### Type Mismatch
71 
72**Error:** `"Cannot cast"` on append.  
73**Cause:** PyArrow types don't match Iceberg schema.  
74**Solution:** Cast to int64 (Iceberg default), not int32. Check `table.schema()`.
75 
76## Compaction Issues
77 
78### Compaction Issues
79 
80**Problem:** File count unchanged or compaction takes hours.  
81**Cause:** Target size too large, or table too big for PyIceberg.  
82**Solution:** Only compact if avg <50MB. For >1TB tables, use Spark. Run during low-traffic periods.
83 
84## Maintenance Issues
85 
86### Snapshot/Orphan Issues
87 
88**Problem:** Expiration fails or orphan cleanup deletes active data.  
89**Cause:** Too aggressive retention or wrong order.  
90**Solution:** Always expire snapshots first with `retain_last=10`, then cleanup orphans with 3+ day threshold.
91 
92## Concurrency Issues
93 
94### Concurrent Write Conflicts
95 
96**Problem:** `CommitFailedException` with multiple writers.  
97**Cause:** Optimistic locking - simultaneous commits.  
98**Solution:** Add retry with exponential backoff (see [patterns.md](patterns.md#pattern-6-concurrent-writes-with-retry)).
99 
100### Stale Metadata
101 
102**Problem:** Old schema/data after external update.  
103**Cause:** Cached metadata.  
104**Solution:** Reload table: `table = catalog.load_table(("ns", "table"))`
105 
106## Performance Optimization
107 
108### Performance Tips
109 
110**Scans:** Use `row_filter` and `selected_fields` to reduce data scanned.  
111**Partitions:** 100-1000 optimal. Avoid high cardinality (millions) or low (<10).  
112**Files:** Keep 100-500MB avg. Compact if <10MB or >10k files.
113 
114## Limits
115 
116| Resource | Recommended | Impact if Exceeded |
117|----------|-------------|-------------------|
118| Tables/namespace | <10k | Slow list ops |
119| Files/table | <100k | Slow query planning |
120| Partitions/table | 100-1k | Metadata overhead |
121| Snapshots/table | Expire >7d | Metadata bloat |
122 
123## Common Error Messages Reference
124 
125| Error Message | Likely Cause | Fix |
126|---------------|--------------|-----|
127| `401 Unauthorized` | Missing/invalid token | Check token has catalog+storage permissions |
128| `403 Forbidden` | Token lacks storage permissions | Add R2 Storage Bucket Item permission |
129| `404 Not Found` | Catalog not enabled or wrong URI | Run `wrangler r2 bucket catalog enable` |
130| `409 Conflict` | Table/namespace already exists | Use try/except or load existing |
131| `422 Unprocessable Entity` | Schema validation failed | Check type compatibility, required fields |
132| `CommitFailedException` | Concurrent write conflict | Add retry logic with backoff |
133| `NamespaceAlreadyExistsError` | Namespace exists | Use try/except or load existing |
134| `NoSuchTableError` | Table doesn't exist | Check namespace+table name, create first |
135| `TypeError: Cannot cast` | PyArrow type mismatch | Cast data to match Iceberg schema |
136 
137## Debugging Checklist
138 
139When things go wrong, check in order:
140 
1411. ✅ **Catalog enabled:** `npx wrangler r2 bucket catalog status <bucket>`
1422. ✅ **Token permissions:** Both R2 Data Catalog + R2 Storage in dashboard
1433. ✅ **Connection test:** `catalog.list_namespaces()` succeeds
1444. ✅ **URI format:** HTTPS, includes `/iceberg/`, correct bucket name
1455. ✅ **Warehouse name:** Matches bucket name exactly
1466. ✅ **Namespace exists:** Create before `create_table()`
1477. ✅ **Enable debug logging:** `logging.basicConfig(level=logging.DEBUG)`
1488. ✅ **PyIceberg version:** `pip install --upgrade pyiceberg` (≥0.5.0)
1499. ✅ **File health:** Compact if >1000 files or avg <10MB
15010. ✅ **Snapshot count:** Expire if >100 snapshots
151 
152## Enable Debug Logging
153 
154```python
155import logging
156logging.basicConfig(level=logging.DEBUG)
157# Now operations show HTTP requests/responses
158```
159 
160## Resources
161 
162- [Cloudflare Community](https://community.cloudflare.com/c/developers/workers/40)
163- [Cloudflare Discord](https://discord.cloudflare.com) - #r2 channel
164- [PyIceberg GitHub](https://github.com/apache/iceberg-python/issues)
165- [Apache Iceberg Slack](https://iceberg.apache.org/community/)
166 
167## Next Steps
168 
169- [patterns.md](patterns.md) - Working examples
170- [api.md](api.md) - API reference
171