Reference

Troubleshooting

Blank pages, broken assets, deep-link 404s, the "check base path" warning, and other common upload issues with App To Page — and how to fix each one.

Almost every issue comes down to one thing: how your build references its assets. Here are the common ones and the fix for each. If you’re still stuck after this, get in touch.

A blank page, or a “check base path” warning

Cause: the build was made with an absolute base — it assumes it’s served from the root of a domain, so its asset links look like /assets/app.js instead of assets/app.js. Mounted at your-site.com/your-app, those links point to the wrong place and nothing loads.

Fix: rebuild with a relative base and update the app:

// Vite
export default { base: './' };
// Create React App (package.json)
{ "homepage": "." }

App To Page rewrites root-absolute paths on upload as a safety net, so an absolute build mounted at its exact slug often still works — but a relative build is portable and warning-free. See Deploy a React or Vite app.

Cause: a client-side router (React Router, Vue Router) owns sub-paths, but single-page app fallback is off, so the server has nothing to serve at that path.

Fix: turn on Single-page app fallback for the app (it’s under Advanced on the confirm card, and on by default). With it on, unknown sub-paths serve your index.html so the router can handle the route.

Some assets load, others 404

Cause: assets referenced with absolute paths, or files that live outside the build output.

Fix: reference assets relatively, and make sure every asset (models, fonts, images) is inside the folder you zipped. For frameworks, put static files in public/ so they land in dist/.

The app card says “Files missing”

Cause: the app’s files couldn’t be found on disk — usually from an interrupted upload.

Fix: open the app’s Manage page, click Update, and re-upload the zip. See Update an app in place.

My zip has an extra wrapping folder

App To Page automatically strips a single wrapping folder (like dist/, or the wrapper macOS adds when you compress a folder), then finds index.html. If your archive nests index.html several folders deep, re-zip the contents of your build folder so index.html is at the top of the archive.

A GitHub deploy can’t find the build

Cause: the repository doesn’t have a built .zip to pull — App To Page serves build output, not source code.

Fix: attach a built .zip to a GitHub Release, or point the app at a branch that contains the built files. If your Release has more than one asset, set the Release asset name so it knows which to use. See Deploy from a GitHub repository.

Run a health check

Not sure what’s wrong? Open the app’s Manage page and look at the Health check — it flags common problems (like a base-path issue) and tells you whether the app looks ready to publish. Click Re-run check after you make a change.

Frequently asked questions

Why is my app a blank page on WordPress?

Almost always an absolute-base build. Rebuild with a relative base (base: './' for Vite, "homepage": "." for CRA) and update the app.

Why does refreshing my app show a 404?

Your app uses client-side routing and single-page app fallback is off. Turn it on (it’s under Advanced, and on by default) so unknown paths fall back to index.html.

My app works locally but not after uploading. What do I check?

Three things: index.html is at the top of the zip, assets use relative paths, and it was built for production. If all three are true and it still won’t serve, contact us and we’ll help.