1# Gotchas
2 
3## Common Errors
4 
5### ".get() Throws on Error"
6 
7**Cause:** Assuming `.get()` returns null on failure instead of throwing  
8**Solution:** Always wrap `.get()` calls in try/catch blocks to handle errors gracefully
9 
10```typescript
11try {
12  const key = await env.API_KEY.get();
13} catch (error) {
14  return new Response("Configuration error", { status: 500 });
15}
16```
17 
18### "Logging Secret Values"
19 
20**Cause:** Accidentally logging secret values in console or error messages  
21**Solution:** Only log metadata (e.g., "Retrieved API_KEY") never the actual secret value
22 
23### "Module-Level Secret Access"
24 
25**Cause:** Attempting to access secrets during module initialization before env is available  
26**Solution:** Cache secrets in request scope only, not at module level
27 
28### "Secret not found in store"
29 
30**Cause:** Secret name doesn't exist, case mismatch, missing workers scope, or incorrect store_id  
31**Solution:** Verify secret exists with `wrangler secrets-store secret list <store-id> --remote`, check name matches exactly (case-sensitive), ensure secret has `workers` scope, and verify correct store_id
32 
33### "Scope Mismatch"
34 
35**Cause:** Secret exists but missing `workers` scope (only has `ai-gateway` scope)  
36**Solution:** Update secret scopes: `wrangler secrets-store secret update <store-id> --name SECRET --scopes workers --remote` or add via Dashboard
37 
38### "JSON Parsing Failure"
39 
40**Cause:** Storing invalid JSON in secret, then failing to parse during runtime  
41**Solution:** Validate JSON before storing:
42 
43```bash
44# Validate before storing
45echo '{"key":"value"}' | jq . && \
46  echo '{"key":"value"}' | wrangler secrets-store secret create <store-id> \
47    --name CONFIG --scopes workers --remote
48```
49 
50Runtime parsing with error handling:
51 
52```typescript
53try {
54  const configStr = await env.CONFIG.get();
55  const config = JSON.parse(configStr);
56} catch (error) {
57  console.error("Invalid config JSON:", error);
58  return new Response("Invalid configuration", { status: 500 });
59}
60```
61 
62### "Cannot access secret in local dev"
63 
64**Cause:** Attempting to access production secrets in local development environment  
65**Solution:** Create local-only secrets (without `--remote` flag) for development: `wrangler secrets-store secret create <store-id> --name API_KEY --scopes workers`
66 
67### "Property 'get' does not exist"
68 
69**Cause:** Missing TypeScript type definition for secret binding  
70**Solution:** Define interface with get method: `interface Env { API_KEY: { get(): Promise<string> }; }`
71 
72### "Binding already exists"
73 
74**Cause:** Duplicate binding in dashboard or conflict between wrangler.jsonc and dashboard  
75**Solution:** Remove duplicate from dashboard Settings → Bindings, check for conflicts, or delete old Worker secret with `wrangler secret delete API_KEY`
76 
77### "Account secret quota exceeded"
78 
79**Cause:** Account has reached 100 secret limit (beta)  
80**Solution:** Check quota with `wrangler secrets-store quota --remote`, delete unused secrets, consolidate duplicates, or contact Cloudflare for increase
81 
82## Limits
83 
84| Limit | Value | Notes |
85|-------|-------|-------|
86| Max secrets per account | 100 | Beta limit |
87| Max stores per account | 1 | Beta limit |
88| Max secret size | 1024 bytes | Per secret |
89| Local secrets | Don't count toward limit | Only production secrets count |
90| Scopes available | `workers`, `ai-gateway` | Must have correct scope for access |
91| Scope | Account-level | Can be reused across multiple Workers |
92| Access method | `await env.BINDING.get()` | Async only, throws on error |
93| Management | Centralized | Via secrets-store commands |
94| Local dev | Separate local secrets | Use without `--remote` flag |
95| Regional availability | Global except China Network | Unavailable in China Network |
96 
97See: [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)
98