404 for homepage when implementing multiregional markets

Shopify Discussion

Topic summary

A Shopify Hydrogen developer successfully implemented multi-regional storefronts with a country selector for US and Singapore markets. However, the homepage routes (/us/ and /sg/) return 404 errors, while all other localized routes function correctly.

The Issue:

  • Despite using ($locale)._index.jsx for the homepage route, accessing /us/ or /sg/ triggers a 404
  • Other routes with locale parameters work as expected

Suggested Troubleshooting Steps:

  • Verify file naming follows Hydrogen’s file-based routing conventions (ensure ($locale)._index.jsx not ($locale)/_index.jsx)
  • Debug the loader function to confirm locale parameters are being captured correctly
  • Review remix.config.js to ensure proper URL processing for locale-based paths
  • Check entry server configuration for handling /us/ and /sg/ requests
  • Consider implementing a fallback _index.jsx route to redirect from base URL to appropriate localized version

Status: The discussion remains open with no confirmed resolution yet.

Summarized with AI on November 1. AI used: claude-sonnet-4-5-20250929.
1

I completed the setup for multi-regional storefronts for my Shopify Hydrogen website (https://shopify.dev/docs/storefronts/headless/hydrogen/markets/multiple-languages-url-paths) and implemented a country selector (https://shopify.dev/docs/storefronts/headless/hydrogen/markets/country-selector) to allow users to change regions based on what country they’re in (currently only selling to US and Singapore).

However, while everything works as intended, the host URL /us/ or /sg/ (e.g. www.hosturl.com/us/, www.hosturl.com/sg/), does not work and triggers a 404. Anyone know why this is the case? I assumed the ($locale) in my homepage route ($locale)._index.jsx would account for this, but it doesn’t seem to work (other routes work fine, it’s just the homepage that’s erroring).

2

Hi @awef194586 , this is Kate fromPageFly. It looks like you’ve set up multi-regional storefronts for your Hydrogen-powered Shopify store, but your homepage route (/us/ or /sg/) is returning a 404 while other localized pages are working correctly. Here are some possible reasons and solutions to address the issue.

  1. Check your file naming
    Hydrogen uses file-based routing, and the homepage route should be correctly named as ($locale)._index.jsx. If the structure is incorrect, such as using ($locale)/_index.jsx, Remix may not recognize it properly. Double-check your file structure to ensure it aligns with Hydrogen’s expected routing.
  2. Verify that locale parameters are being passed correctly
    Hydrogen determines the locale from the URL, but if /us/ or /sg/ isn’t being recognized, the route parameters may not be passing correctly. A good approach is to debug params.locale within the loader function to confirm whether the expected values are being captured.
  3. Adjust the remix router configuration
    Since Hydrogen is built on Remix, its routing behavior may need adjustments to correctly process locale-based URLs. Review your remix.config.js file to ensure that it properly supports /us/ and /sg/.
  4. Ensure your entry server handles locale-based URLs
    If your entry server is not correctly processing requests for /us/ or /sg/, the homepage may not resolve as expected. Adding logging to your entry server can help verify whether these requests are being received and handled properly.
  5. Implement a fallback route to prevent 404 errors
    If Hydrogen is not recognizing /us/ or /sg/ as valid routes, adding a fallback _index.jsx route can help redirect users to the correct storefront automatically. This approach ensures that visitors accessing the base URL (www.hosturl.com/) are directed to the appropriate localized version of the store.

Additionally, if your store supports automatic region detection, consider implementing a redirect from / to /us/ or /sg/ based on the user’s location to provide a seamless browsing experience.

I hope this helps resolve the issue. Let me know if you need further clarification.

Best,
Kate
PageFly – Shopify Landing Page Builder