Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 36 ยท Projects and Practice

Practice: Troubleshooting and Reviewing Packer Templates

A practice lesson with the most common Packer failures (SSH timeouts, plugin errors, hung provisioners, name collisions), a debugging method, a review checklist and self-test exercises.

The last lesson of this part turns your knowledge into habits. You will meet the failures that show up again and again in real Packer projects, learn a debugging method that works for all of them and finish with a review checklist you can apply to any template in a pull request. Then you can test yourself with short exercises.

Packer cannot run on this site, so the messages below are described in words rather than quoted as output, and exact wording varies by version and plugin. The JavaScript examples are stand-in tools for practice.

A debugging method

  1. Reproduce in the smallest form. Build one source with -only, one region, serial (-parallel-builds=1).
  2. Read the first error, not the last. Later errors are usually consequences (cleanup failures after a failed provisioner).
  3. Turn on logs. PACKER_LOG=1 (and PACKER_LOG_PATH) for plugin and API detail; remember logs can contain secrets.
  4. Keep the machine. -on-error=ask or abort lets you SSH in and reproduce the failing command by hand. Clean up afterwards.
  5. Change one thing at a time, and re-run validate after each edit.
  6. Fix at the right layer: template, script, base image, network, permissions or cloud quota.

See validating templates for the commands.

The common failures

Symptom Likely cause What to check
Hangs on "Waiting for SSH" then times out Security group or subnet has no route or public IP; wrong ssh_username; instance never booted Networking, ssh_username for the source image, ssh_timeout, instance console log
Authentication failed for the cloud Missing, expired or wrong-account credentials Credential chain, role assumption, region
Plugin not installed or version constraint error packer init not run or constraint too strict Run packer init, review required_plugins
Source image not found Filter matches nothing, owner wrong, region differs Test the filter with the cloud CLI; check the region
Name already exists Reused ami_name or image name Add version or timestamp; use force options only deliberately
Provisioner hangs Interactive prompt (apt, installer), service waiting for input -y, DEBIAN_FRONTEND=noninteractive, timeouts
Script fails with permission denied Missing sudo or execute_command Run as root with sudo -E
Works locally, fails in CI Different Packer version, missing tools or credentials, different network Pin versions, print tool versions at job start
Cloud-init interferes (apt lock) The first-boot tasks still running when provisioning starts Wait for cloud-init status --wait at the beginning of the first script
Image boots but service is down Service not enabled, wrong user, config uses build-time paths Boot test, systemctl status, journal logs
Leaked resources after a cancelled build Builder instance, volumes, security groups left behind Tag with run_tags; run a janitor job
Quota or rate-limit errors Too many parallel builds or regions Reduce parallelism, request quota increases

The apt lock row is worth memorizing: right after boot, cloud-init often runs package updates, so the first apt-get in your provisioner fails with a lock error. Starting with cloud-init status --wait (or a loop checking the lock) is the standard cure.

Review checklist

Use it on every template change.

Sources

  • Source image filtered by trusted owner; no hard-coded ids that will rot.
  • Unique names with a version; consistent tags; encryption on; IMDSv2 or equivalent.
  • No credentials in the file.

Provisioning

  • Scripts fail on error (set -euo pipefail), are non-interactive and idempotent where possible.
  • Downloads pinned and verified; no curl | sh from the internet.
  • Final cleanup removes keys, histories, caches and temporary users.

Quality

  • fmt, init, validate in CI; shell scripts linted.
  • Build-time spec tests; boot test before promotion.

Pipeline

  • OIDC or short-lived credentials; least-privilege roles; timeouts and concurrency set.
  • Manifest saved; version, SHA and parent recorded.
  • Channels and approval for production; retention and rebuild schedule exist.

Try it: classify an error

JS Error triage helper (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The sample messages are paraphrased for practice and are not exact Packer output.

Try it: review a template

JS Automated review (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Self-test exercises

  1. A build waits for SSH forever, but only in one subnet. List three checks, in order.
  2. Your first apt-get install fails right after boot but works when you retry by hand. What is happening and what is the fix?
  3. Two pipelines build web-base-1.4.0 at the same time. What breaks, and how do you prevent it?
  4. A teammate wants latest as the production image tag. Explain the risk and propose an alternative.
  5. Write three rules for your team's template linter.

Try answering before you reread the lessons on CI, versioning and security.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the first thing to do when a build fails?

    Small reproductions and the first error point to the real cause; later errors are usually consequences.
  2. 2. A first apt-get fails with a lock error right after boot. What is the usual cause?

    Wait for cloud-init to finish before provisioning packages.
  3. 3. Which option keeps the builder machine alive after a failure so you can inspect it?

    ask and abort leave the machine; remember to clean up afterwards.
  4. 4. What is a major risk of curl | sh in a provisioner?

    Pin and verify downloads instead.

Summary

  • Debug by shrinking the problem, reading the first error, enabling logs and keeping the machine.
  • Most failures are networking, credentials, filters, names, interactive prompts or cloud-init timing.
  • Use a review checklist across sources, provisioning, quality and pipeline.
  • Practice with the exercises, then return to the Packer track page for the other chapters.

Next: Back to the Packer track