⚛ React + ASP.NET Core Guide

7. Troubleshooting

SymptomLikely causeFix
"Proxy error" / ECONNREFUSED in the Vite console The API isn't running yet, or the proxy target port is wrong Run the server with the https profile and set target in vite.config.js to its applicationUrl.
Browser shows raw JSON or a Swagger page instead of React Server project is launching its own URL Clear Launch browser for the server's https profile.
Front end doesn't start or can't reach the API Using the http launch profile Switch to the https profile.
Certificate or "connection not private" warnings Dev certificate not trusted dotnet dev-certs https --clean then dotnet dev-certs https --trust, and restart the browser.
First build takes minutes or fails npm is restoring packages, or Node.js is outdated Wait for the first restore; update Node.js and Visual Studio to current versions; delete node_modules and run npm install.
Calls to /api/... return the HTML page Request not matched by the proxy or fallback is intercepting Check the proxy pattern covers the path, and that API routes are mapped before MapFallbackToFile.
Refreshing a deep link gives 404 in production Missing SPA fallback Add app.MapFallbackToFile("/index.html").
React app is blank after publish Client build didn't run or wasn't copied Check wwwroot/index.html exists in the publish output; run npm run build manually to see errors.
CORS errors in the browser console Calling the API on a different origin directly Use relative URLs with the proxy, or configure CORS for the exact origin.
Port already in use A previous dev server is still running Close old console windows or stop the process using that port.

Useful commands

# Reinstall front-end dependencies cleanly
cd reactwithaspnet.client
rm -rf node_modules
npm install

# Build the client by itself to see errors
npm run build

# See which processes use a port (Windows PowerShell)
Get-NetTCPConnection -LocalPort 5173 | Select-Object LocalPort, OwningProcess

Where to learn more