Documentation

Project troubleshooting

Common project-side failure modes, especially when the app built successfully but does not come up healthy.

Try StackShiftRead the overview

Projects

Project troubleshooting

Live

Common project-side failure modes, especially when the app built successfully but does not come up healthy.

Goal

Shorten the path from “deployment failed” to the actual misconfiguration or runtime issue.

Current status

Live

This area is documented as current, user-reliable behavior.

Workflow

  1. 1Check build status first, then deployment status, then runtime logs.
  2. 2Verify service type, workload type, port expectations, and environment variables before assuming a platform problem.
  3. 3Review domains separately from application runtime failures.

Fast classification checks

  • If the project is a worker service, lack of a public URL is expected behavior rather than a routing bug.
  • If the project is contract build, expect build output and logs, not a live runtime or healthcheck URL.
  • If boot is slow, increase startup timeout before assuming the image or platform is broken.

Persistent volume misconfiguration

  • A rejected mount path usually means it targeted a reserved system directory or did not start with `/`.
  • If state disappears after redeploy, confirm persistent volume was enabled and mounted at the path the app actually uses.
  • If storage size changes do not appear immediately, remember that resizing takes effect with redeploy behavior.

Expected result

You can classify a project failure accurately before retrying or rolling back.