AI Search Gotchas
Type Safety
Timestamp precision: Use seconds (10-digit), not milliseconds.
const nowInSeconds = Math.floor(Date.now() / 1000); // CorrectFolder prefix matching: Use gte for "starts with" on paths.
filters: { column: "folder", operator: "gte", value: "docs/api/" } // Matches nestedFilter Limitations
| Limit | Value |
|---|---|
| Max nesting depth | 2 levels |
| Filters per compound | 10 |
or operator |
Same column, eq only |
OR restriction example:
// ✅ Valid: same column, eq only
{ operator: "or", filters: [
{ column: "folder", operator: "eq", value: "docs/" },
{ column: "folder", operator: "eq", value: "guides/" }
]}Indexing Issues
| Problem | Cause | Solution |
|---|---|---|
| File not indexed | Unsupported format or >4MB | Check format (.md/.txt/.html/.pdf/.doc/.csv/.json) |
| Index out of sync | 6-hour index cycle | Wait or use "Force Sync" (30s rate limit) |
| Empty results | Index incomplete | Check dashboard for indexing status |
Auth Errors
| Error | Cause | Fix |
|---|---|---|
AutoRAGUnauthorizedError |
Invalid/missing token | Create Service API token with AI Search permissions |
AutoRAGNotFoundError |
Wrong instance name | Verify exact name from dashboard |
Performance
Slow responses (>3s):
// Add score threshold + limit results
ranking_options: { score_threshold: 0.5 },
max_num_results: 10Empty results debug:
- Remove filters, test basic query
- Lower
score_thresholdto 0.1 - Check index is populated
Limits
| Resource | Limit |
|---|---|
| Instances per account | 10 |
| Files per instance | 100,000 |
| Max file size | 4 MB |
| Index frequency | 6 hours |
Anti-Patterns
Use env vars for instance names:
const answer = await env.AI.autorag(env.AI_SEARCH_INSTANCE).aiSearch({...});Handle specific error types:
if (error instanceof AutoRAGNotFoundError) { /* 404 */ }
if (error instanceof AutoRAGUnauthorizedError) { /* 401 */ }