references/static-assets/gotchas.md
Static Assets Gotchas
Compare the deployed build output and effective configuration with the exact request that failed. Test browser navigation separately from client-side fetches when investigating SPA routing.
| Symptom or decision | Documentation | |---------------------|---------------| | Asset missing or unexpected files uploaded | Asset directory and ignore rules | | Worker is bypassed for an asset or protected path | Worker-first routing | | Browser navigation returns HTML for an API path | SPA navigation requests and advanced routing | | Unexpected redirects or trailing slashes | HTML handling | | A missing route serves the wrong fallback | SPA routing or SSG custom 404 pages | | Cache behavior or custom headers differ from expectations | Default and custom headers | | Vite development and deployment behave differently | Vite asset configuration and output | | Worker-first requests return 429 or affect cost | Billing and limitations | | Asset count or file size exceeds deployment limits | Static asset platform limits | | Placement adds latency to asset requests | Worker routing and placement caveat |
Verify a public asset, API endpoint, protected path, and missing URL against the routing intent. Inspect response status, redirect location, and cache headers before changing fallback or cache configuration. Return to configuration.md and api.md for the relevant settings and binding behavior.