> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Project troubleshooting

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

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

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

## Prerequisites

* An existing project

## Workflow

<Steps>
  <Step>
    Check build status first, then deployment status, then runtime logs.
  </Step>

  <Step>
    Verify service type, workload type, port expectations, and environment variables before assuming a platform problem.
  </Step>

  <Step>
    Review domains separately from application runtime failures.
  </Step>
</Steps>

## 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

<Check>
  You can classify a project failure accurately before retrying or rolling back.
</Check>