How to Toubleshoot Deployment Failures on PipeOps
You start deploying your application and something goes wrong. What do you do? Deploying applications can usually go unexpectedly. This guide provides troubleshooting tips that can help you resolve common issues.
Check Deployment Logs
If your project fails to deploy or start, you can check what’s the cause in your build logs and app logs. Often, the errors shown there are descriptive enough to point you in the right direction.
You can access build logs during the deployment process to debug issues like missing dependencies, failing steps, or syntax errors that prevent a successful build. App logs are also available for runtime logs from the application.
Example: In the logs below, we see that the deployment failed due to a MongoDB connection issue. This tells us where to look.
After checking our environment variables, we realized that the database name in the MONGO_URI connection string was incorrect.
Once we updated the value and redeployed the project, the deployment completed successfully.
Bottom line: Logs offer insight into the build and deployment process. If anything goes wrong, they are often your best bet in finding out the root cause of the problem.
Use the Events Timeline
We highly recommend checking the Events tab. It provides a chronological list of actions related to your deployment, like "Pulled image," "Container started," "Startup probe failed," and so on. This is especially useful for understanding when and where something went wrong.
To view events associated with your deployment:
- Navigate to your project.
- Click the "Events" tab as shown below.
Verify Environment variables
Your deployment can fail if the port it exposes doesn’t match the one you set in your PipeOps environment variables. For example, your application can build successfully yet fail to deploy.
Here’s how to confirm your environment variables are correctly configured:
- Go to your project settings
- Access the environment variables tab
- Verify that the PORT and other variables are correctly set
Auto-Deployment & Repository Visibility Issues
If your project doesn’t pick up new changes made to your GitHub repository, you can fix that by installing the PipeOps Git App. This solution also works for situations where you don’t see your private repositories when trying to deploy.
To install the PipeOps Git app:
- Follow the process for deploying a web project
- Select your GitHub account
- Click the “Install PipeOps Git” button
Once installed:
- Auto-deployments will trigger correctly on new commits.
- Private repositories will become visible when selecting repos.
Validate Configuration Files
Incorrect or incomplete configuration files are a frequent source of deployment errors. Common culprits include Dockerfile, package.json (for Node.js apps), next.config.js (for Next.js), .env.example, etc.
What to do:
-
Ensure your files are valid and present in your repository.
-
Confirm that these files have the right syntax and content.
-
Double-check that start scripts exist and run as expected locally.
Additional Troubleshooting Tips
-
Avoid unnecessary lifecycle commands: Adding a lifecycle command without verifying that it works can break your deployment. Only add what you need, and test locally first.
-
Check for missing dependencies: If a required package isn’t listed in your project’s dependency file, your deployment may break. Double-check that all needed packages are included in package.json, requirements.txt, etc.
Deployment issues can be frustrating, but most have clear, repeatable fixes. With this guide and the tools available on PipeOps, including logs and events, you can identify problems faster and ship confidently.
If you’ve tried these solutions and still need help, don’t hesitate to reach out.