Waymaker
Waymaker Host

Troubleshooting Deployments

Learn about Troubleshooting Deployments in WaymakerOS.

TroubleshootingDeployments

Common deployment issues and how to resolve them.

Build Fails Immediately

Symptom: Deployment shows "failed" status within seconds.

Check:

  1. Is the branch correct? Open Settings and verify the branch matches your repository
  2. Is the repository connected? The settings page should show Pipeline active
  3. Is your GitHub integration still authorised? Go to Host > GitHub to verify the connection

Build Fails During Build Step

Symptom: Deployment starts but fails partway through.

Check:

  1. Is the build command correct? Common commands:
FrameworkBuild CommandOutput Directory
React (Vite)npm run builddist
Next.jsnpm run build.next
Vuenpm run builddist
Astronpm run builddist
Sveltenpm run buildbuild
  1. Is the output directory correct? It must match what your build command produces
  2. For monorepo projects, is the root directory set correctly? Host runs the build command from this directory

App Deploys But Shows Blank Page

Symptom: Deployment succeeds but the app URL shows a blank white page.

Check:

  1. Open your browser's developer console (F12) for error messages
  2. Verify the output directory — if it points to the wrong folder, the CDN serves nothing
  3. Check that your app builds correctly locally with the same build command
  4. For single-page apps (React, Vue), verify your router is configured for the hosting environment

App Deploys But Shows Old Version

Symptom: You pushed new code but the app still shows the previous version.

Check:

  1. Verify a new deployment was triggered — check the Deployments tab for a recent entry
  2. Hard-refresh your browser (Cmd+Shift+R or Ctrl+Shift+R) to clear the cache
  3. Check that you pushed to the correct branch — Host only deploys from the configured branch

Custom Domain Not Working

Symptom: Your custom domain shows an error or "not found" page.

Check:

  1. Verify DNS records are configured correctly — see Custom Domains
  2. DNS changes can take up to 48 hours to propagate (usually much faster)
  3. SSL certificates are provisioned automatically but may take a few minutes after DNS verification

Environment Variable Issues

Symptom: App works locally but fails in production, or certain features are broken.

Check:

  1. Verify all required environment variables are set in Host > Environment Variables
  2. Environment variable names are case-sensitive
  3. Variables set in Host are available at build time and runtime — check that your app reads them correctly
  4. After changing environment variables, trigger a new deployment by pushing to your repository

Still Having Issues?

If none of the above resolves your problem:

  1. Check the deployment status and any error messages in the Deployments tab
  2. Verify your app builds and runs correctly in your local development environment
  3. Try deploying a minimal version of your app to isolate the issue
  4. Contact support with the app name and a screenshot of the error

Next Steps