Skip to main content
Most deployment issues on Pxxl fall into one of three categories: an old build artifact that can no longer be rolled back to, a port mismatch that causes a 503 after you change your app’s listener, or a static site returning 404s on nested routes because the hosting mode does not match your build output. Use the accordions below to identify your situation and follow the fix steps.
Pxxl stores build artifacts for a window defined by your plan’s retention policy. The deployment history always remains visible in the dashboard, but once an artifact ages out of the retention window, rollback can no longer recreate the container image from that old build.What artifact retention meansWhen you trigger a rollback, Pxxl needs the original image layers to recreate the container exactly. If those layers have expired, the rollback entry is visible but non-functional — the platform has no image to launch.Your options
  • Redeploy the same commit. Push or select the commit again to trigger a fresh build from source. The resulting image will be functionally identical to the expired one.
  • Upgrade your plan. Higher-tier plans keep artifacts for longer, giving you more rollback headroom for critical releases.
  • Tag releases in Git. Keep a named tag (for example v2.4.1) on every release commit so you can always find and redeploy the exact version even after the artifact expires.
Use Git tags for production releases. A tag makes it trivial to redeploy a specific version without searching through commit history.
The Pxxl edge proxy routes traffic through the runtime route registry to the active container port for your project. If you change the port your app listens on — either in your code or in project settings — make sure the project port matches the app listener and resync the proxy so the active upstream is refreshed.Why port alignment mattersPxxl registers the active container port in the runtime route map. If your app process binds to a different port inside the container, TCP connections from the proxy are refused and the upstream is considered unhealthy. Updating the port in settings is necessary, and a redeploy is only required when the running image itself needs the changed port/config value.Fix steps
1

Open the project

Go to Dashboard > Projects and select the affected project.
2

Go to Settings

Open the Settings tab.
3

Update the port

Change the port value to match the port your application actually binds to at startup.
4

Redeploy the project

Trigger a new deployment. This rebuilds or re-pulls the image and starts the container with the updated port label.
5

Resync the proxy for each connected domain

Open Domains, select each domain connected to this project, and click Resync Proxy so the edge upstream target reflects the new port.
Where possible, configure your app to read the PORT environment variable at startup. This makes it easier to keep the app and Pxxl settings aligned without code changes.
If a static site works fine at / but returns 404 when you navigate to a nested path like /blog or /dashboard, the problem is a mismatch between how your build output is structured and how the project is configured to serve it.Plain HTML sites vs. SPAsHow to fix it
  • Plain HTML site: Make sure your build step generates a real file for each URL. For example, /blog requires either blog.html or blog/index.html in the output directory.
  • SPA build: Confirm the project was detected as the correct framework (for example React Vite) before deployment. Pxxl uses the framework detection to configure the correct fallback behaviour. If the framework was misidentified, update the framework setting and redeploy.
Redeploy after changing settingsChanging the framework or build output configuration only takes effect on the next deployment. Trigger a redeploy after making any framework or output directory change.
Serving an SPA without a fallback rule means every direct link or browser refresh to a nested path will return 404. Always confirm the correct framework is selected before deploying a client-side router application.