Troubleshooting Deployments

Common Deployment Failures

Build Fails

Symptoms: Deployment status shows "failed" during the building phase.

Common causes:

• Missing Dockerfile: If your repo doesn't have a Dockerfile and framework auto-detection doesn't find a supported framework, the build can't proceed. Add a Dockerfile to your repository root.
• Incorrect Dockerfile syntax: Check your Dockerfile for syntax errors. The build logs (visible on the tenant detail page) will show the exact line that failed.
• Missing dependencies: Ensure your package.json, requirements.txt, go.mod, or equivalent dependency file is committed and up to date.
• Private dependency access: If your build requires private npm packages or Python packages, add the necessary auth tokens as environment variables.

Container Crashes (CrashLoopBackOff)

Symptoms: Deployment status shows "running" briefly, then the service restarts repeatedly.

Common causes:

• Missing environment variables: Your app is trying to read a variable that isn't set. Check the Shared Env tab and redeploy.
• Database connection failure: If your app tries to connect to the database on startup and fails, it will crash. Verify DATABASE_URL is set and the database is provisioned.
• Port mismatch: Your app is listening on a different port than what's configured in Staxa. Check that the port in your service configuration matches what your app actually binds to.
• Startup timeout: Your app takes too long to start and the health check fails. Optimize startup time or check for blocking operations during initialization.

Out of Memory (OOMKilled)

Symptoms: The container is killed and restarted. Logs may show "OOMKilled" in the deployment events.

Solution: Your application is exceeding its memory limit. Either optimize memory usage or move to a larger resource size (Small → Medium → Large) in the service configuration. Medium needs the Growth or Scale plan, and Large needs Scale.

Image Pull Errors

Symptoms: Deployment fails during the deploying phase with "image pull" errors.

Common causes:

• Invalid image URL: Double-check the image URL for typos
• Private registry without credentials: Go to Settings → Container Registries and add credentials for your registry. Make sure the credential is verified (green checkmark).
• Image tag doesn't exist: Verify the tag you specified exists in your registry

SSL Certificate Not Ready

Symptoms: Your tenant URL returns a certificate error in the browser.

Solution: SSL certificates are provisioned automatically by cert-manager and Let's Encrypt. This typically takes 30–90 seconds after deployment. If it takes longer, the domain verification may be failing. Check that your subdomain DNS is resolving correctly.

Getting Build Logs

Build and deployment logs are available on the tenant detail page:

1. Navigate to your tenant
2. Find the service in the Services tab
3. Expand the deployment history
4. Click on the failed deployment to see detailed logs

Logs include the full build output (Dockerfile commands, dependency installation, compilation) and any runtime errors during startup.

Still Stuck?

If you've checked all of the above and the issue persists, contact support at support@staxa.dev with:

• Your tenant name
• The deployment ID (visible in the deployment history)
• A description of what you expected vs. what happened