---
title: "AI Search Gotchas"
description: "**Timestamp precision:** Use seconds (10-digit), not milliseconds. ```typescript const nowInSeconds = Math.floor(Date.now() / 1000); // Correct ```"
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/gotchas-1
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:24:59.717Z
license: CC-BY-4.0
attribution: "AI Search Gotchas — Claudary (https://claudary.paisolsolutions.com/skills/gotchas-1)"
---

# AI Search Gotchas
**Timestamp precision:** Use seconds (10-digit), not milliseconds. ```typescript const nowInSeconds = Math.floor(Date.now() / 1000); // Correct ```

## Overview

# AI Search Gotchas

## Type Safety

**Timestamp precision:** Use seconds (10-digit), not milliseconds.
```typescript
const nowInSeconds = Math.floor(Date.now() / 1000); // Correct
```

**Folder prefix matching:** Use `gte` for "starts with" on paths.
```typescript
filters: { column: "folder", operator: "gte", value: "docs/api/" } // Matches nested
```

## Filter Limitations

| Limit | Value |
|-------|-------|
| Max nesting depth | 2 levels |
| Filters per compound | 10 |
| `or` operator | Same column, `eq` only |

**OR restriction example:**
```typescript
// ✅ 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):**
```typescript
// Add score threshold + limit results
ranking_options: { score_threshold: 0.5 },
max_num_results: 10
```

**Empty results debug:**
1. Remove filters, test basic query
2. Lower `score_threshold` to 0.1
3. 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:**
```typescript
const answer = await env.AI.autorag(env.AI_SEARCH_INSTANCE).aiSearch({...});
```

**Handle specific error types:**
```typescript
if (error instanceof AutoRAGNotFoundError) { /* 404 */ }
if (error instanceof AutoRAGUnauthorizedError) { /* 401 */ }
```

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/gotchas-1) · https://claudary.paisolsolutions.com