Skip to main content

Packer Troubleshooting

This guide covers common issues you might encounter when using Atmos with Packer and how to resolve them.

Configuration Errors​

Packer Base Path Not Configured​

Error:

packer base path is required: must be provided in 'components.packer.base_path' config or 'ATMOS_COMPONENTS_PACKER_BASE_PATH' ENV variable

Cause: The Packer component base path is not configured in your atmos.yaml.

Solution: Add the Packer configuration to your atmos.yaml:

components:
  packer:
    base_path: components/packer

Or set the environment variable:

export ATMOS_COMPONENTS_PACKER_BASE_PATH=components/packer

Component Not Found​

Error:

invalid component: 'my-component' points to the Packer component 'my-component', but it does not exist in 'components/packer'

Cause: The specified component doesn't exist in the Packer components directory.

Solution:

  1. Verify the component name matches a directory under your Packer base path
  2. Check for typos in the component name
  3. Ensure the component is defined in your stack configuration

Stack Not Specified​

Error:

stack is required; specify it on the command line using the flag `--stack <stack>` (shorthand `-s`)

Cause: The --stack flag was not provided.

Solution: Always specify the stack when running Packer commands:

atmos packer build my-ami -s prod

Build Errors​

Abstract Component Cannot Be Provisioned​

Error:

abstract component cannot be provisioned: the component 'aws/bastion' cannot be provisioned because it's marked as abstract (metadata.type: abstract)

Cause: You're trying to build a component marked as abstract in the stack configuration.

Solution: Abstract components are templates meant to be inherited, not built directly. Either:

  1. Remove the metadata.type: abstract from the component configuration
  2. Create a concrete component that inherits from the abstract one
  3. Use a non-abstract component for building

Locked Component Cannot Be Modified​

Error:

locked component cannot be modified: component 'aws/bastion' cannot be modified (metadata.locked: true)

Cause: You're trying to build a component that has been locked to prevent modifications.

Solution:

  1. If the lock is intentional, use a different component
  2. If the lock should be removed, update the stack configuration to set metadata.locked: false

AWS Credentials Not Found​

Error:

no valid credential sources found
NoCredentialProviders: no valid providers in chain

Cause: Packer cannot find AWS credentials to authenticate with AWS.

Solution:

  1. Configure AWS credentials using one of these methods:

    • AWS CLI: aws configure
    • Environment variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
    • IAM role (when running on EC2)
    • AWS SSO: aws sso login

  2. Or set credentials in your stack configuration:

    components:
      packer:
        my-ami:
          env:
            AWS_PROFILE: my-profile
            AWS_REGION: us-east-1

Plugin Not Installed​

Error:

Missing plugins: amazon

Cause: Required Packer plugins haven't been installed.

Solution: Run packer init before building:

atmos packer init my-ami -s prod
atmos packer build my-ami -s prod

Template Errors​

Unsupported Attribute​

Error:

Unsupported attribute: var.my_variable

Cause: A variable is referenced in the template but not defined.

Solution:

  1. Ensure all variables are defined in variables.pkr.hcl or within your template
  2. If using multiple files, ensure Atmos is using directory mode (default)
  3. Check that your settings.packer.template is not pointing to a single file when you have multiple files

Template File Not Found​

Error:

stat template.pkr.hcl: no such file or directory

Cause: The specified template file doesn't exist.

Solution:

  1. Use the default directory mode by not specifying --template (recommended)
  2. If using --template, ensure the file exists in the component directory
  3. Use --template . to explicitly load all *.pkr.hcl files

Invalid HCL Syntax​

Error:

Error: Invalid block definition

Cause: Syntax error in your Packer HCL template.

Solution:

  1. Run atmos packer validate my-ami -s prod to see detailed error messages
  2. Use atmos packer fmt my-ami -s prod to auto-format your templates
  3. Check for missing brackets, quotes, or commas

Output Errors​

Manifest File Not Found​

Error:

packer manifest is missing: manifest.json does not exist

Cause: The Packer manifest file doesn't exist. This happens when:

  1. packer build hasn't been run yet
  2. The manifest post-processor isn't configured
  3. A different manifest filename is used

Solution:

  1. Run atmos packer build first to generate the manifest
  2. Ensure your template includes the manifest post-processor: 
    post-processor "manifest" {
      output = "manifest.json"
    }
  3. If using a custom manifest filename, specify it in vars: 
    vars:
      manifest_file_name: my-manifest.json

Invalid YQ Query​

Error:

yq: Error: Invalid query syntax

Cause: The YQ query expression is invalid.

Solution:

  1. Test your query with the standalone yq tool first
  2. Ensure proper quoting of the query expression
  3. Common queries: 
    # Get first artifact ID
    atmos packer output my-ami -s prod --query '.builds[0].artifact_id'

    # Get AMI ID from artifact
    atmos packer output my-ami -s prod -q '.builds[0].artifact_id | split(":")[1]'

Debugging Tips​

Enable Debug Logging​

Add verbose logging to see what Atmos is doing:

export ATMOS_LOGS_LEVEL=Debug
atmos packer build my-ami -s prod

Enable Packer Logging​

Enable Packer's built-in logging for detailed build information:

components:
  packer:
    my-ami:
      env:
        PACKER_LOG: "1"
        PACKER_LOG_PATH: "/tmp/packer.log"

Inspect Component Configuration​

View the resolved component configuration:

atmos describe component my-ami -s prod

Validate Before Building​

Always validate your templates before building:

atmos packer validate my-ami -s prod

Inspect Template Structure​

See what sources, variables, and builders are defined:

atmos packer inspect my-ami -s prod