bug(404 Error): GitHub pages default 404 page redirect on refresh

[manu-059]

Describe your issue

The issue is whenever user refresh a page other than the landing page (https://ryan-millard.github.io/Img2Num/about), 404 page not found is shown. The site works locally , this issues happens only in production.

Steps to reproduce

1. Go to hosted Production URL
2. Click on about link Header
3. Refresh the page
4. 404 Error page is being shown

What was the expected result?

1. Page with it's appropriate content should load.

Put here any screenshots or videos (optional)

Notice the URL and the page (unrelated to the Img2Num).

Would you like to work on this issue?

Yes

[Ryan-Millard]

Hi, thanks for opening this issue!

I noticed this problem a while ago and attempted to fix it using public/404.html, but that didn’t work. Looking back, I suspect the redirect logic was incorrect 😅

I’ve struggled to find a clean solution because this behavior is specific to GitHub Pages and how it handles static hosting. At this point, migrating to a different hosting platform may genuinely be the simplest long-term fix — but I want to explore all reasonable options first.

Important

The documentation site is not affected by this issue.

What I believe is happening

GitHub Pages only serves static files. When a user refreshes or directly visits a client-side route like:

/Img2Num/about

GitHub Pages tries to locate a corresponding static file:

about.html
about/index.html

When it can’t find one, it returns a server-side 404. At that point, GitHub Pages redirects to the root of the domain (which doesn’t host anything for this project):

https://ryan-millard.github.io/

This explains why the app works perfectly when accessing:

https://ryan-millard.github.io/Img2Num/

The index.html file exists at that route, mounts the React app, and from there React Router handles all navigation client-side without further server requests.

Tip

You can inspect exactly what GitHub Pages is serving by looking at the gh-pages branch.

Why the docs site works

The documentation site is built with Docusaurus, which generates fully static HTML files for every route at build time. That means GitHub Pages always finds a matching file, so no 404 occurs.

This strongly suggests the issue is not React-specific, but a limitation of static hosting + client-side routing.

Possible solutions (and trade-offs)

1. Fixing the 404.html redirect logic

There may be a bug in public/404.html — specifically around line 7 — that causes redirects to drop the /Img2Num base path and send users to the domain root instead.

If this is true, the fix may be relatively small and elegant. This needs more investigation and testing.

2. Serve index.html as 404.html (SPA fallback)

A common GitHub Pages workaround is to copy index.html to 404.html during the build process. When a route isn’t found, GitHub Pages serves 404.html, which then boots the React app and lets React Router resolve the route.

This avoids hash routing, preserves clean URLs, and doesn’t require per-route files.

Downsides:

• Still a hack
• Returns a 404 status code initially (minor SEO implications)

3. Generate static files for every route

We could mimic Docusaurus and generate static entry points (credits/index.html, etc.) that all mount the React app.

This would work, but:

• It increases build complexity
• It’s easy to forget to add new routes
• It bloats the output
• It feels brittle and manual

Not something I’m excited about maintaining.😅

4. Switching to HashRouter

This would technically solve the issue immediately.

However:

• URLs become uglier and less meaningful
• Deep linking and sharing degrade
• Extra work is needed to regain features we already have

I’d prefer to avoid this unless there’s no better alternative.

5. Migrate away from GitHub Pages

Platforms like Vercel, Netlify, or Cloudflare Pages support SPA route fallbacks natively and solve this problem cleanly with zero hacks.

This is currently the most robust long-term solution, but it does add hosting complexity and would completely change the URL that the site uses (domain name change).

6. Switching to SSR (for completeness)

Another theoretical solution would be to migrate the app from a purely client-side SPA to server-side rendering (SSR).

In practice, this would mean replacing the current Vite + React SPA setup with something like Next.js, Tanstack Start, Remix, or Astro (SSR mode).

Example (Next.js-style SSR route):

// app/about/page.tsx (Next.js App Router)
export default function AboutPage() {
  return <About />;
}

The key difference is that the server renders /about as real HTML, so refreshing or directly visiting routes works naturally without hacks.

Why this is not trivial

• GitHub Pages cannot host SSR
• Requires a new hosting platform (Vercel, Netlify, Fly.io, etc.)
• Routing, data fetching, and build output all change
• Client-only assumptions break
• Build tooling, deploy pipeline, and environment variables change
• This would be a large, invasive refactor (borderline demonic)

SSR does solve the problem cleanly, but the cost is high and probably unjustified unless we want:

• SEO-first rendering
• Server-backed features
• A long-term platform shift

For now, SSR feels like overkill compared to static SPA fallbacks or simply switching hosts — but it’s worth mentioning as a “nuclear option” if the project ever outgrows static hosting. It could be nice in case we ever decide to use server-side image processing (if users want that) because we'd already have the infrastructure set up.

Where I’m at

At the moment, I don’t think this is a bug in Img2Num itself, but rather a known limitation of GitHub Pages. That said, I’m very open to better ideas and want this solved.

Looking for recommendations

I'd really appreciate input from anyone reading this on:

• A cleaner GitHub Pages workaround
• Experience fixing this exact issue without hash routing
• Strong opinions on whether migration is the right call

Thanks again for raising this and for your patience — this is one of those annoying SPA-on-static-hosting edge cases.

[Ryan-Millard]

This issue has turned into a broader discussion around hosting strategy, routing, and long-term architecture (SPA fallbacks vs SSR vs migration).

Since there isn’t a single clear “bug fix” here, I’m going to convert this to a Discussion so we can gather opinions and recommendations without treating it as a blocking issue.

If/when we settle on a concrete approach, I’ll open a new issue to track implementation.

[manu-059]

@Ryan-Millard , one approach which i have personally used to resolve this is , to have web.config file in final build ,with below content. ( basically saying “If the file doesn’t exist, always serve index.html” )

`<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="React Routes" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>
`

pros:
✔ Fixes 404 on page refresh
✔ Supports deep links (/profile/123)
✔ Works with BrowserRouter
✔ No React code changes
✔ Production-safe & widely used

Let me know your thoughts 💡.

[Ryan-Millard]

@Ryan-Millard , one approach which i have personally used to resolve this is , to have web.config file in final build ,with below content. ( basically saying “If the file doesn’t exist, always serve index.html” )

`<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="React Routes" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>
`

pros:
✔ Fixes 404 on page refresh
✔ Supports deep links (/profile/123)
✔ Works with BrowserRouter
✔ No React code changes
✔ Production-safe & widely used

Let me know your thoughts 💡.

Hey @manu-059! Thanks for the input.

What kind of server have you used it on? I’m not sure if this would work on GitHub Pages or other static hosts because web.config is specific to IIS servers. GitHub Pages doesn’t support server-side rewrites, so any configuration like this would be ignored. On static hosts, unknown routes usually just return a 404 unless you use something like the possible solutions I mentioned previously.

[manu-059]

in my case i had used Azure App Service for hosting , Wasn't aware that GitHub Pages doesn’t support server-side rewrites,
we need to find other solution.

[Ryan-Millard]

The 404.html fix seems like the best option . I will be creating an issue for it now and closing this discussion.

Thank you for your help with this, @manu-059!

[Ryan-Millard]

It seems like the best fix is to use the 404.html option. I created #181 for this fix.