Why Does a Shopify App Proxy Return a 404?

The real symptom

• A request to /apps/your-path returns 404.
• The backend endpoint works when called directly.
• The proxy worked in development but fails after install or deployment.
• A duplicate proxy path might have been renamed with a suffix such as -1.

The likely causes

• The installed app’s proxy subpath differs from the path hard-coded in storefront code.
• The [app_proxy] values in shopify.app.toml were changed but not deployed.
• The public Shopify path and the private backend route were confused.
• The backend does not handle the child route Shopify forwards.
• The app lacks the required app-proxy capability or scope.
• The request method is not handled by the backend route.
• The app is checking the wrong path after Shopify forwards the request.

Confirmed Community fix

A confirmed Shopify Community solution was to inspect the installed app’s actual proxy configuration. Shopify can alter a duplicate proxy subpath, so code calling /apps/badge might need to call /apps/badge-1 instead. The storefront request, TOML configuration, and installed app details must all agree.

Check the installed proxy path

1. In Shopify admin, go to Settings → Apps and sales channels.
2. Find the app and open its details.
3. Inspect the app proxy path that Shopify assigned.
4. Compare it with the URL used by your Liquid, JavaScript, theme app extension, or UI extension.

Check shopify.app.toml

[app_proxy]
url = "/my-app-proxy"
prefix = "apps"
subpath = "my-custom-path"

With that configuration, the storefront calls:

https://your-store.myshopify.com/apps/my-custom-path

Shopify forwards the request to:

https://your-app-domain.com/my-app-proxy

A child request such as /apps/my-custom-path/orders must be handled by the corresponding child route on your backend.

Deploy configuration changes

Changes made to shopify.app.toml during local development do not automatically update every production install. Deploy the app configuration with Shopify CLI and verify the active app version afterward.

DevTools checks

1. Open the storefront and launch browser DevTools.
2. Use the Network panel to inspect the failing request.
3. Confirm the request begins with the store domain and the expected /apps/... path.
4. Check whether the response is a true 404, a redirect, an HTML password page, or a backend error page.
5. Check backend logs to determine whether the request reached the app at all.

Do not call the private backend URL from storefront code

The purpose of the app proxy is to expose a Shopify-domain route that forwards to your application. Storefront code should usually call the public Shopify proxy path, while the url value identifies the route inside your application.

Sources

• Shopify Community: App Proxy not working
• Shopify Community: Unable to find App Proxy settings
• Shopify Developer Docs: App proxies and dynamic data
• Shopify Developer Docs: App configuration