Puppet "Could not retrieve catalog ... compilation failed" in CI

Puppet compiles a node's manifests into a catalog before applying. When compilation fails (a syntax error, an undefined variable, a missing class, or an unresolved dependency), the agent cannot retrieve a catalog and the run aborts.

What this error means

puppet agent/apply fails with "Could not retrieve catalog from remote server: Error 500 on SERVER: ... compilation failed" or "Evaluation Error: ...", naming the manifest and line.

Error: Could not retrieve catalog from remote server: Error 500 on SERVER: Server
Error: Evaluation Error: Error while evaluating a Resource Statement, Could not find
declared class profile::web at /etc/puppetlabs/code/.../site.pp:12:3

Common causes

A missing class or module

A manifest declares a class that is not in the module path, so compilation cannot resolve it.

A syntax or evaluation error

A parse error, an undefined variable in strict mode, or a bad parameter value stops the catalog from compiling.

How to fix it

Validate and compile locally

1. Run puppet parser validate on the manifests to catch syntax errors.
2. Ensure required modules are installed so declared classes resolve.
3. Compile the catalog for the node to reproduce the evaluation error.

puppet parser validate manifests/site.pp
puppet module install puppetlabs-apache

Resolve module dependencies in CI

Install modules from a Puppetfile with r10k/librarian so the catalog has every class it declares.

r10k puppetfile install
puppet catalog compile node.example.com

How to prevent it

• Run puppet parser validate in CI before deploy.
• Install module dependencies via a Puppetfile.
• Test catalog compilation for representative nodes.

Related guides