In 2026, after Vue project deployment, a 404 appears on refresh—is that a routing misconfiguration or a server setup problem?

In 2026, if your Vue project returns 404 on refresh after being built and deployed, do not rush to modify the route code. Based on repeated delivery experience, the vast majority of such 404s happen because the history mode is used while the server does not fall back to index.html for unmatched paths. The actual fix usually lies not in the front-end source code, but in the URL fallback configuration of the deployment environment. This article provides a four-step checking approach and the cost ranges for three common deployment types, and explains when it makes more sense to use history mode and when hash mode is easier.

First distinguish two 404 types to identify where to check

A white screen or 404 on refresh and a first-visit 404 are different issues. First-visit 404s usually mean the server root or the entry file is wrong; refresh 404s usually mean the routing mode and server fallback rules do not match. If you first classify the symptom into one of these two tracks, you can save a lot of time when checking configs.

• 404 on first visit: First check whether the server root points to the dist directory, then verify that index.html actually exists.
• Click navigation works, but manual refresh returns 404: Focus on history routing and server fallback rules.
• Sometimes it opens, sometimes it is 404: First suspect CDN or browser caching of the old entry file, or static asset paths lost under a subdirectory.

From experience, in refresh-404 scenarios, about 70 percent are due to the server missing an SPA fallback rule, 20 percent are cache issues, and the rest may be lazy-loaded chunks blocked or a wrong publicPath subdirectory.

Vue refresh 404: the four-step verification approach

This sequence comes from the same phenomenon observed in multiple Vue project deliveries. If you follow it, most configuration-caused 404s can be resolved within an experience range of 0.5 to 2 hours. If you start changing business code first, you are more likely to take a detour.

1. Verify deployment contents: Confirm that index.html exists on the server and that the root path returns it. In actual delivery, sometimes only part of the built files are uploaded, or the dist contents are scattered into a second-level directory, causing a 404.
2. Verify publicPath: When deploying at the domain root, use the default; when deploying in a subdirectory, set publicPath to the matching subpath. A wrong setting usually causes a white screen and 404 static assets, not route-refresh 404s, and these two are often mixed up.
3. Verify server fallback: The server must point all requests without a corresponding real file to index.html. For Nginx a common configuration is try_files; for a Node service use a catch-all route; for static hosting platforms enable the SPA fallback.
4. Verify cache and CDN: In some cases the server is configured, but the old HTML is cached by the browser or CDN, so a refresh still gets the old version. At that point, handle the cache headers and the status code returned after fallback together.

Among the four steps, Step 3 is the most common missing piece. If the first three all pass and a refresh 404 still occurs, check whether the lazy-loaded route chunk files are being blocked by server security policies. According to our statistics, the vast majority of 404s caused by configuration mistakes are exposed within the first two steps.

History mode itself does not generate 404; a missing fallback rule does

History mode changes the URL through the HTML5 History API, but when the page is refreshed, the browser sends a request to the server with the full path from the address bar. If the server only recognizes the root path and does not map addresses such as /list/123 to the entry page, it returns 404. Hash mode puts the route content after the # sign, and that part is not sent to the server, so no fallback rule is needed by default.

• History mode: The URL is clean, good for sharing and analytics; the trade-off is that when you change deployment environments, you need to check whether server fallback works.
• Hash mode: Minimal server requirements, almost no extra configuration; the trade-off is the # in the address bar, which requires extra handling in some sharing and tracking scenarios.

When the business side insists on history mode only because the # in the URL looks bad, do not agree immediately. Write the server support status into the technical risk list before scheduling. This step is especially important in 2026, because many static hosting platforms have simplified the configuration entry, but quite a few of them also turn off the fallback feature.

Configure fallback by deployment type: approaches, costs and common settings

In 2026 there are three common deployment types, and each has its own focus. First clarify which type of service you use, and then decide which layer the fallback rule belongs to; that will help avoid detours.

Self-hosted Nginx

The acceptance criterion is whether the location configuration redirects requests that miss a real file to index.html. A typical practice is configuring try_files in the server block. Check the exact syntax against your version and the official documentation, and make sure real static files are not incorrectly fallen back. The experience cost range is about 0.5 to 1 hour.

Node server

After static-file handling, add a catch-all route so GET requests return index.html. The acceptance criterion is that page paths other than static assets no longer return 404. If the project does not already have a Node layer, you should budget an extra 1 to 2 hours for the server-side change and deployment scheduling.

Static hosting platform or OSS/CDN

When the platform supports it, enable SPA fallback in the console or config file. When it does not, refreshing deep routes will almost always return 404. Then you either switch to hash mode or move the project to a service with a Node runtime. If the platform natively supports SPA fallback, enabling it is cheap: roughly 10 to 20 minutes. If not, you need to reselect the platform, and the total change may take 0.5 to 1 day.

Here is a comparable cost set: hash mode needs almost no operational changes, but the URL contains #; history mode + Nginx fallback costs about 0.5 to 1 hour; history mode + SPA fallback enabled on a static hosting platform costs roughly 10 to 20 minutes; if the platform is unsupported, you need to migrate or add a lightweight middleware layer, which usually takes 0.5 to 1 day.

A real delivery: the rework caused by one refresh 404

This is a real rework case. In a delivery project in 2026, the client chose history mode, the server was pure static hosting, and the budget allowed only uploading static files, not renting a Node instance. At that time I reminded the team that the platform needed to support URL fallback, but the related console option was off by default and no one noticed it in time. As a result, function-testing passed, but the acceptance side got a 404 on refresh and the page was inaccessible. Later, when we enabled SPA fallback on the platform and adjusted the CDN cache settings, the issue was closed.

This rework cost about half a day extra, and the acceptance schedule was pushed back. To prevent it from the source, add 'whether the route contains #' into technical constraints during the requirements phase, and confirm the deployment environment's URL rewriting capability. This has nothing to do with the UI, but it directly affects the go-live time; the earlier you check it, the better.

Applicable scenarios and boundaries

History mode is suitable for sites that need clean URLs, have long-term stable content paths, and can control the server or platform fallback rules. Hash mode is more suitable for internal management systems, marketing H5 pages, demo environments, and pure static hosting spaces where you have no server-side configuration permission.

• History is worth using: You own a formal domain, can configure routes by yourself, and page paths have long-term sharing and analytics value.
• Do not force history mode: For temporary campaign pages, pure presentation H5 pages, or an internal admin backend, hash mode can be delivered sooner and does not affect functional acceptance.
• Do not expect a pure front-end fix: The authority to fix the refresh 404 is on the server side. The frontend can only switch to hash mode, or move the project to SSR/prerendering, rather than adding a script inside the build artifact to pretend the page is fine.

If you do not have server permissions yourself, prefer switching to hash mode, or ask your operations team to enable URL rewriting. Do not change both ends at the same time unless you are prepared to introduce a new mismatch.

FAQ

Can the frontend handle the refresh-404 problem without any server change?

No. By the time a refresh request reaches the frontend code, the server has already returned an error page. The only solutions are to switch to hash mode or let the server apply a wildcard fallback. There is no pure front-end option.

I already have try_files configured in Nginx, but a refresh still returns 404. Why?

First confirm the directive is placed in the correct server or location block. Then check whether it only covers the root path. For subdirectory deployment, match the relevant path prefix at the same time, and verify publicPath as well.

The business insists on removing #, but the hosting platform does not support fallback. What can I do?

The only choice is to add a Node layer or use a service that supports URL rewriting. From experience on real projects, schedule this change window before development starts to avoid rework before launch.

Some routes get a 404 on refresh, but others are normal. Is it a route-file problem?

Usually it is not a route-file error; instead, a deep route path is not matched by the fallback rule, or lazy-loaded chunks are blocked by server policies. Start with the four-step checks to examine the fallback configuration.

Action guide: In the project development phase, add whether the deployment environment can configure URL fallback to your requirements checklist. If a refresh 404 occurs after go-live, first follow the four-step check to solve it from the server side. This article applies to traditional Vue SPA deployments. For content sites that need long-term SEO indexing, the refresh 404 is only the surface issue; you also need to evaluate the investment boundary of SSR or prerendering.