Skip to main content

Troubleshooting & FAQ

Common issues and how to resolve them.

Deployment Issues​

My deployment is stuck or not progressing​

Possible causes:

  • Waiting for approval — Check if a Terraform approval, test approval, or bake period is pending. Go to the deployment in the dashboard and look for steps with an "Awaiting Approval" status.
  • Deployment window — If a stage has a deployment time window configured, deployments will queue until the window opens. See Deployment Windows.
  • Stage is blocked — A previous rollback may have blocked the stage. Check Stage Controls for how to unblock.
  • Resource timeout — ECS or EKS deployments may be waiting for containers to become healthy. Check the step logs for progress details.

My deployment timed out​

Each step type has a configurable timeout parameter (in minutes). If a step exceeds its timeout, it fails. Check the step logs for what was happening when the timeout occurred, and consider increasing the timeout value in your pipeline definition.

Any branch push triggers a deployment​

Currently, any push to any branch of a connected repository triggers a deployment. All branches go through the same pipeline stages. Branch filtering is not yet supported — plan your branching strategy accordingly, or use a single deployment branch.

My rollback didn't work as expected​

Rollbacks re-execute the deployment steps from a previous revision against the stage. Key things to know:

  • Infrastructure steps (Terraform) are skipped by default during rollbacks to avoid unintended infrastructure changes.
  • The rollback deploys the artifacts from the selected previous revision.
  • After a rollback, the stage is automatically blocked from further promotions until you manually unblock it. See Unblock After Rollback.

Build Issues​

My artifact isn't rebuilding​

DevRamps uses a cache key based on the rebuild_when_changed paths to decide whether to rebuild an artifact. If the files under those paths haven't changed since the last successful deployment, the artifact is reused from cache.

To force a rebuild:

  • Make any change to a file under the rebuild_when_changed paths and push.
  • Verify that your rebuild_when_changed paths are correct — they should cover your source code, Dockerfile, and any build-related files.

Docker build is failing​

Common causes:

  • Wrong architecture — If your ECS service runs on ARM (Graviton), make sure your artifact's architecture is set to arm64, not the default amd64.
  • Missing dependencies — Check that your Dockerfile installs all required build dependencies.
  • Build context — The build_context and dockerfile_path are relative to your repository root.

Check the build logs in the dashboard for the specific error message.

Bootstrap & CLI Issues​

Bootstrap failed​

Common causes:

  • Wrong credentials — Ensure your AWS CLI is configured with credentials that have administrator access to the target account. Run aws sts get-caller-identity to verify.
  • Insufficient permissions — The bootstrap process needs permissions to create CloudFormation stacks, IAM roles, and OIDC providers. Administrator access is recommended.
  • Account already bootstrapped — If the account was previously bootstrapped, the CloudFormation stack may already exist. Check your CloudFormation console for a DevRamps stack.

Recommended approach: Always run npx @devramps/cli bootstrap --dry-run first to preview what will be created before making any changes.

See the CLI troubleshooting section for more specific error messages.

When do I need to re-bootstrap?​

You need to re-bootstrap an AWS account when:

  • You add a new step type to your pipeline that requires additional IAM permissions.
  • You want to update the IAM policies that DevRamps uses in your account.
  • DevRamps releases a new version of the bootstrap stack.

Re-bootstrapping updates the existing CloudFormation stack — it does not create duplicate resources.

Pipeline Configuration Issues​

Pipeline synthesis failed​

Pipeline synthesis validates your pipeline.yaml when a deployment starts. Common errors:

  • Invalid YAML syntax — Check for indentation errors, missing colons, or unclosed quotes.
  • Unknown step type — Verify the step type matches a registered step (e.g., DEVRAMPS:ECS:DEPLOY, not ECS:DEPLOY).
  • Missing required fields — Check that all required parameters for each step are provided.
  • Invalid expressions — Ensure ${{ }} expressions reference valid objects (e.g., stage.account_id, not account_id).

Expression resolved to empty or undefined​

If an expression like ${{ vars.my_var }} resolves to an empty value:

  • Check that the variable is defined in the stage's vars section.
  • Check spelling and case sensitivity — variable names are case-sensitive.
  • Step output references (${{ steps.my_step.output_name }}) are only available after the referenced step has completed.

Terraform Issues​

Terraform plan shows unexpected changes​

  • State drift — If someone made manual changes to infrastructure outside of DevRamps, Terraform will detect drift and plan changes to bring the state back in line.
  • State file location — DevRamps stores Terraform state in an S3 bucket in your CI/CD account. Make sure no other process is managing the same resources with a different state file.

Where is my Terraform state stored?​

Terraform state is stored in an S3 bucket in your CI/CD account. DevRamps manages the state backend configuration automatically — you don't need to configure a backend in your Terraform files.

General FAQ​

What languages and frameworks does DevRamps support?​

DevRamps is language-agnostic. Any application that can be packaged as a Docker image or a file bundle can be deployed. This includes Node.js, Python, Go, Java, Ruby, .NET, static sites, and more. See Supported Platforms.

Does DevRamps work with GitLab, Bitbucket, or other Git providers?​

No. DevRamps currently requires GitHub. Support for other Git providers is not yet available.

What AWS regions are supported?​

DevRamps can deploy to any AWS region. Your pipeline stages specify the target region in the deployment_target configuration.

How do I get an API token?​

API tokens can be generated from the DevRamps dashboard under your organization settings. All API requests require a bearer token for authentication.

Can I use DevRamps without AWS?​

No. DevRamps is built specifically for AWS deployments. Support for other cloud providers is not currently available.