1# Flagship Gotchas & Troubleshooting
2 
3## Common Errors
4 
5### Flag Always Returns Default Value
6 
7**Cause:** Flag is disabled (`enabled: false`), or no targeting rules match, or evaluation context is missing expected attributes.
8 
9**Solution:** Check these in order:
10 
111. Is the flag enabled? (`"enabled": true`)
122. Do your targeting rules match the context you're passing?
133. Are you passing the right attributes in the evaluation context?
14 
15```typescript
16// ❌ BAD — no context, rules can't match
17const val = await env.FLAGS.getBooleanValue("my-flag", false);
18 
19// ✅ GOOD — pass context attributes that rules reference
20const val = await env.FLAGS.getBooleanValue("my-flag", false, {
21  userId: "user-42",
22  plan: "enterprise",
23});
24```
25 
26### TYPE_MISMATCH Error in Details
27 
28**Cause:** Calling a typed method on a flag with a different type (e.g., `getBooleanValue` on a string flag).
29 
30**Solution:** Use the method matching the flag's variation type.
31 
32```typescript
33// ❌ BAD — flag "checkout-flow" has string variations
34const val = await env.FLAGS.getBooleanValue("checkout-flow", false);
35 
36// ✅ GOOD
37const val = await env.FLAGS.getStringValue("checkout-flow", "original");
38```
39 
40### 409 Conflict on Flag Creation
41 
42**Cause:** A flag with that key already exists in the app.
43 
44**Solution:** Use a different key, or GET + PUT to update the existing flag.
45 
46### Inconsistent Rollout Results
47 
48**Cause:** `targetingKey` (or the configured bucketing attribute) is missing from the evaluation context, causing random bucketing on each request.
49 
50**Solution:** Always pass a stable identifier:
51 
52```typescript
53// ❌ BAD — no targetingKey, rollout is random per request
54const val = await env.FLAGS.getBooleanValue("gradual-rollout", false);
55 
56// ✅ GOOD — stable userId for consistent bucketing
57const val = await env.FLAGS.getBooleanValue("gradual-rollout", false, {
58  userId: sessionUserId,
59});
60```
61 
62### Update Overwrites Entire Flag
63 
64**Cause:** PUT replaces the full `FlagDefinition`. Sending only changed fields deletes the rest.
65 
66**Solution:** Always read-modify-write:
67 
68```bash
69# ❌ BAD — overwrites the entire flag, losing rules/variations
70curl -X PUT -d '{"enabled": true}' ...
71 
72# ✅ GOOD — GET first, modify, PUT back
73FLAG=$(curl -s -H "Authorization: Bearer $TOKEN" "$URL/flags/my-flag" | jq '.data')
74UPDATED=$(echo "$FLAG" | jq '.enabled = true')
75echo "$UPDATED" | curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d @- "$URL/flags/my-flag"
76```
77 
78### FLAG_NOT_FOUND in Client Provider
79 
80**Cause:** Flag key not included in `prefetchFlags` array.
81 
82**Solution:** Add the flag key to `prefetchFlags` when initializing `FlagshipClientProvider`.
83 
84### Client Provider Token Exposure
85 
86**Cause:** The `authToken` passed to `FlagshipClientProvider` is visible in the browser. It can evaluate flags across all apps in the account.
87 
88**Solution:** Use a token with minimal permissions (Flagship Evaluate only). Never use a token with write/management permissions in the browser.
89 
90---
91 
92## Limits
93 
94| Limit | Value | Notes |
95|-------|-------|-------|
96| Flag key length | 1-64 chars | Alphanumeric, hyphens, underscores only |
97| Flag key pattern | `/^[a-zA-Z0-9_-]+$/` | — |
98| Variation value size | 10KB max | Per variation, serialized |
99| Variation name length | 64 chars max | Alphanumeric, hyphens, underscores |
100| Description length | 512 chars max | Nullable |
101| App name length | 1-64 chars | Alphanumeric, hyphens, underscores |
102| Logical nesting depth | 6 levels | AND/OR conditions |
103| Mutation rate limit | 60 / 60s | Per account:app |
104| Read rate limit | 600 / 60s | Per account:app |
105| Rollout percentage | 0-100 | Integer |
106| Rule priorities | Unique integers >= 1 | Lower = evaluated first |
107 
108---
109 
110## Anti-Patterns
111 
112### Evaluating Flags in a Tight Loop
113 
114Flag evaluation via the binding is fast but not free. Avoid evaluating the same flag repeatedly in a loop — evaluate once and reuse the result.
115 
116```typescript
117// ❌ BAD
118for (const item of items) {
119  const enabled = await env.FLAGS.getBooleanValue("my-flag", false, ctx);
120  // ...
121}
122 
123// ✅ GOOD
124const enabled = await env.FLAGS.getBooleanValue("my-flag", false, ctx);
125for (const item of items) {
126  // use `enabled`
127}
128```
129 
130### Using the SDK Inside Workers When Binding Is Available
131 
132The binding avoids HTTP overhead entirely. Only use the SDK inside Workers when you specifically need OpenFeature vendor-neutrality.
133 
134```typescript
135// ❌ Unnecessary HTTP overhead inside a Worker
136const provider = new FlagshipServerProvider({
137  appId: "...", accountId: "...", authToken: "...",
138});
139 
140// ✅ Use the binding directly, or pass it to the SDK
141const provider = new FlagshipServerProvider({ binding: env.FLAGS });
142```
143 
144### Partial PUT Updates
145 
146The flag update API (PUT) requires the complete `FlagDefinition`. Sending only changed fields silently drops everything else. Always GET first, then modify and PUT back the full object.
147 
148### Stale Flag Cleanup
149 
150Flags that are disabled and no longer referenced in code should be deleted. Stale flags clutter the dashboard and make it harder to understand which flags are active. Follow the safe deletion workflow in `patterns.md`.
151 
152---
153 
154## Propagation Behavior
155 
156Flag changes propagate globally within seconds. During the brief propagation window, some regions may serve the previous value. After propagation completes, all evaluations return the updated value.
157 
158- No Worker redeployment needed for flag changes.
159- If the dashboard is temporarily unavailable, evaluation continues using the last propagated configuration.
160- Flag changes made via the REST API and dashboard are equivalent — both trigger propagation.
161