1# Gotchas & Troubleshooting
2 
3## Execution Order
4 
5**Problem:** Rules execute in unexpected order
6**Cause:** Misunderstanding phase execution
7**Solution:**
8 
9Phases execute sequentially (can't be changed):
101. `http_request_firewall_custom` - Custom rules
112. `http_request_firewall_managed` - Managed rulesets
123. `http_ratelimit` - Rate limiting
13 
14Within phase: top-to-bottom, first match wins (unless `skip`)
15 
16```typescript
17// WRONG: Can't mix phase-specific actions
18await client.rulesets.create({
19  phase: 'http_request_firewall_custom',
20  rules: [
21    { action: 'block', expression: 'cf.waf.score gt 50' },
22    { action: 'execute', action_parameters: { id: 'managed_id' } }, // WRONG
23  ],
24});
25 
26// CORRECT: Separate rulesets per phase
27await client.rulesets.create({ phase: 'http_request_firewall_custom', rules: [...] });
28await client.rulesets.create({ phase: 'http_request_firewall_managed', rules: [...] });
29```
30 
31## Expression Errors
32 
33**Problem:** Syntax errors prevent deployment
34**Cause:** Invalid field/operator/syntax
35**Solution:**
36 
37```typescript
38// Common mistakes
39'http.request.path' → 'http.request.uri.path' // Correct field
40'ip.geoip.country eq US' → 'ip.geoip.country eq "US"' // Quote strings
41'http.user_agent eq "Mozilla"' → 'lower(http.user_agent) contains "mozilla"' // Case sensitivity
42'matches ".*[.jpg"' → 'matches ".*\\.jpg$"' // Valid regex
43```
44 
45Test expressions in Security Events before deploying.
46 
47## Skip Rule Pitfalls
48 
49**Problem:** Skip rules don't work as expected
50**Cause:** Misunderstanding skip scope
51**Solution:**
52 
53Skip types:
54- `ruleset: 'current'` - Skip remaining rules in current ruleset only
55- `phases: ['phase_name']` - Skip entire phases
56 
57```typescript
58// WRONG: Trying to skip managed rules from custom phase
59// In http_request_firewall_custom:
60{
61  action: 'skip',
62  action_parameters: { ruleset: 'current' },
63  expression: 'ip.src in {192.0.2.0/24}',
64}
65// This only skips remaining custom rules, not managed rules
66 
67// CORRECT: Skip specific phases
68{
69  action: 'skip',
70  action_parameters: {
71    phases: ['http_request_firewall_managed', 'http_ratelimit'],
72  },
73  expression: 'ip.src in {192.0.2.0/24}',
74}
75```
76 
77## Update Replaces All Rules
78 
79**Problem:** Updating ruleset deletes other rules
80**Cause:** `update()` replaces entire rule list
81**Solution:**
82 
83```typescript
84// WRONG: This deletes all existing rules!
85await client.rulesets.update({
86  zone_id: 'zone_id',
87  ruleset_id: 'ruleset_id',
88  rules: [{ action: 'block', expression: 'cf.waf.score gt 50' }],
89});
90 
91// CORRECT: Get existing rules first
92const ruleset = await client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });
93await client.rulesets.update({
94  zone_id: 'zone_id',
95  ruleset_id: 'ruleset_id',
96  rules: [...ruleset.rules, { action: 'block', expression: 'cf.waf.score gt 50' }],
97});
98```
99 
100## Override Conflicts
101 
102**Problem:** Managed ruleset overrides don't apply
103**Cause:** Rule ID doesn't exist or category name incorrect
104**Solution:**
105 
106```typescript
107// List managed ruleset rules to find IDs
108const ruleset = await client.rulesets.get({
109  zone_id: 'zone_id',
110  ruleset_id: 'efb7b8c949ac4650a09736fc376e9aee',
111});
112console.log(ruleset.rules.map(r => ({ id: r.id, description: r.description })));
113 
114// Use correct IDs in overrides
115{ action: 'execute', action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee', 
116  overrides: { rules: [{ id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log' }] } } }
117```
118 
119## False Positives
120 
121**Problem:** Legitimate traffic blocked
122**Cause:** Aggressive rules/thresholds
123**Solution:**
124 
1251. Start with log mode: `overrides: { action: 'log' }`
1262. Review Security Events to identify false positives
1273. Override specific rules: `overrides: { rules: [{ id: 'rule_id', action: 'log' }] }`
128 
129## Rate Limiting NAT Issues
130 
131**Problem:** Users behind NAT hit rate limits too quickly
132**Cause:** Multiple users sharing single IP
133**Solution:**
134 
135Add more characteristics: User-Agent, session cookie, or authorization header
136```typescript
137{
138  action: 'block',
139  expression: 'http.request.uri.path starts_with "/api"',
140  action_parameters: {
141    ratelimit: {
142      characteristics: ['cf.colo.id', 'ip.src', 'http.request.cookies["session"][0]'],
143      period: 60,
144      requests_per_period: 100,
145    },
146  },
147}
148```
149 
150## Performance Issues
151 
152**Problem:** Increased latency
153**Cause:** Complex expressions, excessive rules
154**Solution:**
155 
1561. Skip static assets early: `action: 'skip'` for `\\.(jpg|css|js)$`
1572. Path-based deployment: Only run managed on `/api` or `/admin`
1583. Disable unused categories: `{ category: 'wordpress', enabled: false }`
1594. Prefer string operators over regex: `starts_with` vs `matches`
160 
161## Limits & Quotas
162 
163| Resource | Free | Pro | Business | Enterprise |
164|----------|------|-----|----------|------------|
165| Custom rules | 5 | 20 | 100 | 1000 |
166| Rate limiting rules | 1 | 10 | 25 | 100 |
167| Rule expression length | 4096 chars | 4096 chars | 4096 chars | 4096 chars |
168| Rules per ruleset | 75 | 75 | 400 | 1000 |
169| Managed rulesets | Yes | Yes | Yes | Yes |
170| Rate limit characteristics | 2 | 3 | 5 | 5 |
171 
172**Important Notes:**
173- Rules execute in order; first match wins (except skip rules)
174- Expression evaluation stops at first `false` in AND chains
175- `matches` regex operator is slower than string operators
176- Rate limit counting happens before mitigation
177 
178## API Errors
179 
180**Problem:** API calls fail with cryptic errors
181**Cause:** Invalid parameters or permissions
182**Solution:**
183 
184```typescript
185// Error: "Invalid phase" → Use exact phase name
186phase: 'http_request_firewall_custom'
187 
188// Error: "Ruleset already exists" → Use update() or list first
189const rulesets = await client.rulesets.list({ zone_id, phase: 'http_request_firewall_custom' });
190if (rulesets.result.length > 0) {
191  await client.rulesets.update({ zone_id, ruleset_id: rulesets.result[0].id, rules: [...] });
192}
193 
194// Error: "Action not supported" → Check phase/action compatibility
195// 'execute' only in http_request_firewall_managed
196// Rate limit config only in http_ratelimit phase
197 
198// Error: "Expression parse error" → Common fixes:
199'ip.geoip.country eq "US"'   // Quote strings
200'cf.waf.score gt 40'         // Use 'gt' not '>'
201'http.request.uri.path'      // Not 'http.request.path'
202```
203 
204**Tip**: Test expressions in dashboard Security Events before deploying.
205