1# AI Search Gotchas
2 
3## Type Safety
4 
5**Timestamp precision:** Use seconds (10-digit), not milliseconds.
6```typescript
7const nowInSeconds = Math.floor(Date.now() / 1000); // Correct
8```
9 
10**Folder prefix matching:** Use `gte` for "starts with" on paths.
11```typescript
12filters: { column: "folder", operator: "gte", value: "docs/api/" } // Matches nested
13```
14 
15## Filter Limitations
16 
17| Limit | Value |
18|-------|-------|
19| Max nesting depth | 2 levels |
20| Filters per compound | 10 |
21| `or` operator | Same column, `eq` only |
22 
23**OR restriction example:**
24```typescript
25// ✅ Valid: same column, eq only
26{ operator: "or", filters: [
27  { column: "folder", operator: "eq", value: "docs/" },
28  { column: "folder", operator: "eq", value: "guides/" }
29]}
30```
31 
32## Indexing Issues
33 
34| Problem | Cause | Solution |
35|---------|-------|----------|
36| File not indexed | Unsupported format or >4MB | Check format (.md/.txt/.html/.pdf/.doc/.csv/.json) |
37| Index out of sync | 6-hour index cycle | Wait or use "Force Sync" (30s rate limit) |
38| Empty results | Index incomplete | Check dashboard for indexing status |
39 
40## Auth Errors
41 
42| Error | Cause | Fix |
43|-------|-------|-----|
44| `AutoRAGUnauthorizedError` | Invalid/missing token | Create Service API token with AI Search permissions |
45| `AutoRAGNotFoundError` | Wrong instance name | Verify exact name from dashboard |
46 
47## Performance
48 
49**Slow responses (>3s):**
50```typescript
51// Add score threshold + limit results
52ranking_options: { score_threshold: 0.5 },
53max_num_results: 10
54```
55 
56**Empty results debug:**
571. Remove filters, test basic query
582. Lower `score_threshold` to 0.1
593. Check index is populated
60 
61## Limits
62 
63| Resource | Limit |
64|----------|-------|
65| Instances per account | 10 |
66| Files per instance | 100,000 |
67| Max file size | 4 MB |
68| Index frequency | 6 hours |
69 
70## Anti-Patterns
71 
72**Use env vars for instance names:**
73```typescript
74const answer = await env.AI.autorag(env.AI_SEARCH_INSTANCE).aiSearch({...});
75```
76 
77**Handle specific error types:**
78```typescript
79if (error instanceof AutoRAGNotFoundError) { /* 404 */ }
80if (error instanceof AutoRAGUnauthorizedError) { /* 401 */ }
81```
82