name: tanstack-start-routing-debug
description: Debug 404 routes in TanStack Start VPS apps. Find the real cause (nginx proxy vs app routing), fix Portuguese/English slug mismatches via nginx redirects, and verify build output.
trigger: "404 on a TanStack Start route, or button onClick not firing despite correct code."
steps:
- "1. Identify route name in source: grep -n 'createFileRoute' src/routes/*.tsx"
- "2. Verify in build manifest: grep '/clients' dist/server/assets/_tanstack-start-manifest_*.js"
- "3. Inspect response: curl -s 'https://domain.com/clientes' -L | head -20"
- "4. If HTML shows 404 from TanStack Start (not nginx): the route path in createFileRoute is definitive. If nginx 404: proxy_pass wrong or missing."
- "5. For /clientes -> /clients redirect (when app uses English route but users expect Portuguese): use nginx regex BEFORE proxy_pass"
- "6. nginx pattern: location ~ ^/clientes(/.*)?$ { return 301 https://domain.com/clients$1; }"
- "7. Exact /clientes -> / : location = /clientes { return 301 https://domain.com/; }"
- "8. Reload: sudo nginx -t && sudo nginx -s reload"
- "9. Verify: curl -sI 'https://domain.com/clientes/UUID' -L | grep -E 'HTTP|location'"
pitfalls:
- "nginx location order: regex (~) evaluates before prefix (/). Put redirect rules BEFORE proxy_pass location /"
- "return 301 /clients$request_uri loses UUID from /clientes/UUID because $request_uri = /clientes/UUID. Use regex capture $1 instead."
- "grep with ASCII dash (-) will NOT find em-dash (U+2014) in minified bundles. Use python3 binary search."
- "Vite cache in node_modules/.vite can prevent client bundle updates. rm -rf dist node_modules/.vite .vite before npm run build."
- "Radix Dialog warning in console for a page using native div modal: old Radix bundle is still loaded for OTHER pages that use Radix Dialog. Normal, not the bug."
verification:
- "curl -sI 'https://domain.com/clientes/UUID' -L shows 301 + location: /clients/UUID + 200"
- "Browser DevTools shows clients._id-XXXX.js loading without 404"
- "Button onClick fires: Console shows [Dialog] opening log"
references: []
Summary
When a TanStack Start (Lovable-style) app on VPS returns 404 for a route that exists in the source, the problem can be nginx proxy misconfiguration OR the app simply using a different URL path than users expect.
Diagnostic flow:
1. Check source route: createFileRoute("/clients/$id") means URL is /clients/ID, NOT /clientes/ID
2. Check build manifest in dist/server/assets/_tanstack-start-manifest_*.js for route paths
3. Test with curl -s 'https://domain.com/clientes' -L — if it returns TanStack Start 404 HTML, the app route path is the issue
4. Fix with nginx redirect using regex capture: location ~ ^/clientes(/.*)?$ { return 301 https://domain.com/clients$1; }
5. Always put redirect locations BEFORE the proxy_pass location / block in nginx