dotfiles/dot_agents/skills/cloudflare/references/secrets-store/gotchas.md

Gotchas

Common Errors

".get() Throws on Error"

Cause: Assuming .get() returns null on failure instead of throwing
Solution: Always wrap .get() calls in try/catch blocks to handle errors gracefully

try {
  const key = await env.API_KEY.get();
} catch (error) {
  return new Response("Configuration error", { status: 500 });
}

"Logging Secret Values"

Cause: Accidentally logging secret values in console or error messages
Solution: Only log metadata (e.g., "Retrieved API_KEY") never the actual secret value

"Module-Level Secret Access"

Cause: Attempting to access secrets during module initialization before env is available
Solution: Cache secrets in request scope only, not at module level

"Secret not found in store"

Cause: Secret name doesn't exist, case mismatch, missing workers scope, or incorrect store_id
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

"Scope Mismatch"

Cause: Secret exists but missing workers scope (only has ai-gateway scope)
Solution: Update secret scopes: wrangler secrets-store secret update <store-id> --name SECRET --scopes workers --remote or add via Dashboard

"JSON Parsing Failure"

Cause: Storing invalid JSON in secret, then failing to parse during runtime
Solution: Validate JSON before storing:

# Validate before storing
echo '{"key":"value"}' | jq . && \
  echo '{"key":"value"}' | wrangler secrets-store secret create <store-id> \
    --name CONFIG --scopes workers --remote

Runtime parsing with error handling:

try {
  const configStr = await env.CONFIG.get();
  const config = JSON.parse(configStr);
} catch (error) {
  console.error("Invalid config JSON:", error);
  return new Response("Invalid configuration", { status: 500 });
}

"Cannot access secret in local dev"

Cause: Attempting to access production secrets in local development environment
Solution: Create local-only secrets (without --remote flag) for development: wrangler secrets-store secret create <store-id> --name API_KEY --scopes workers

"Property 'get' does not exist"

Cause: Missing TypeScript type definition for secret binding
Solution: Define interface with get method: interface Env { API_KEY: { get(): Promise<string> }; }

"Binding already exists"

Cause: Duplicate binding in dashboard or conflict between wrangler.jsonc and dashboard
Solution: Remove duplicate from dashboard Settings → Bindings, check for conflicts, or delete old Worker secret with wrangler secret delete API_KEY

"Account secret quota exceeded"

Cause: Account has reached 100 secret limit (beta)
Solution: Check quota with wrangler secrets-store quota --remote, delete unused secrets, consolidate duplicates, or contact Cloudflare for increase

Limits

Limit	Value	Notes
Max secrets per account	100	Beta limit
Max stores per account	1	Beta limit
Max secret size	1024 bytes	Per secret
Local secrets	Don't count toward limit	Only production secrets count
Scopes available	workers, ai-gateway	Must have correct scope for access
Scope	Account-level	Can be reused across multiple Workers
Access method	await env.BINDING.get()	Async only, throws on error
Management	Centralized	Via secrets-store commands
Local dev	Separate local secrets	Use without --remote flag
Regional availability	Global except China Network	Unavailable in China Network

See: configuration.md, api.md, patterns.md