references/bindings/gotchas.md
Binding Gotchas and Troubleshooting
Start by checking the binding name, selected environment, and actual target resource. Regenerating types alone does not fix a missing runtime binding.
| Symptom or question | What to check | | --- | --- | | A binding is undefined or points to unexpected data | Binding configuration and environment inheritance | | TypeScript cannot find a binding or runtime type | Current type generation and TypeScript setup | | Updated credentials are not reflected in a client | Binding changes and retained global state; verify the secret's environment and deployment | | Binding calls fail outside a handler | Environment access and global-scope restrictions | | A service target is unavailable or incorrect | Service bindings and multi-Worker development | | Local data, secrets, or available bindings differ from deployment | Development mode support, local data, and local secrets | | KV reads appear stale or return no value | How KV works; verify the namespace and handle missing values | | Resource-specific API errors or limits | Follow the product from the binding catalog to its troubleshooting and limits documentation | | Worker resource limits or unexpected charges | Workers limits and pricing; check each bound product's limits and pricing separately | | Need to inspect configuration, resources, deployments, or logs | Wrangler commands and real-time logs |
Never log secret values or return the environment object in a response. Inspect names and configuration without exposing credentials. Check the selected resource and development mode before issuing debugging commands that could mutate remote data.