# Troubleshoot a deployment

Find the failing layer before changing a working configuration.

Source: https://webhost.photonspark.com/docs/troubleshooting

## Build or startup failure

- EROFS / read-only filesystem: startup is trying to modify the deployed artifact. Install and build earlier; use /tmp only for disposable files.
- Missing vite or a compiler at startup: development dependencies were pruned. Run the compiled server, or select node-static for a static build.
- Missing publish directory: check the selected build mode and ensure the build produces index.html in a supported output directory.
- Connection refused / runtime not Ready: inspect startup logs, bind to 0.0.0.0, and match the configured port and health path.
- Git fetch error: check repository access, branch, deploy key or HTTPS token, and the verified SSH host key. An upstream failure can leave an older release serving normally.

## Public hostname failure

- DNS does not resolve: check registrar delegation and the required A/CNAME records before changing the application.
- TLS error: inspect certificate issuance and DNS/challenge reachability.
- HTTP 404: check whether the route exists in your application and whether the correct release is serving. A reachable origin may intentionally return 404.
- HTTP 401: check whether application authentication or an App's Basic Auth gate is expected.
- HTTP 502 for SparkTunnel: verify the connector process, its network connection, and reachability of the configured local target.
- Frontend works but API fails: verify routing.apiPrefix, the backend health route, and the URL the frontend actually calls.

## Give an agent useful evidence

Share the chosen deployment method, build mode, sanitized manifest, intended hostname, source revision, HTTP status, and the relevant error excerpt. Remove tokens, cookies, database URLs, and other credentials.

Ask the agent to identify the failing layer and propose the smallest change that preserves working behavior. A browser console without errors does not rule out stale status, upstream failures, or a server-side problem.

- [Copy an agent brief](https://webhost.photonspark.com/docs/agents)