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 to the port it registered for your container when the project was last deployed. If you change the port your app listens on — either in your code or in project settings — without redeploying and resyncing, the route points to a port that nothing is listening on, and every request returns 503.Why port alignment mattersPxxl labels the container with the port defined in project settings and configures the upstream target accordingly. 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 but not sufficient — you must also redeploy so the new label reaches the running container, and resync so the proxy picks up the new upstream address.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 Dashboard > 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. SPAs
Site typeHow routing worksWhat you need
Plain HTMLThe server looks for a real file at the requested pathblog/index.html, dashboard/index.html, etc. must exist in the build output
SPA (React, Vue, Svelte, etc.)The client-side router handles all pathsThe server must fall back to index.html for every path that is not a static asset
How 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.