puppetlabs/puppet · error · ArgumentError

The environment directory '%{env_dir}' does not exist

Error message

The environment directory '%{env_dir}' does not exist

What it means

in_environment with the env_dir option verifies the directory exists (Puppet::FileSystem.exist?) before building the environment; env_dir is where the environment lives on disk and its modules/ subdirectory becomes the default modulepath. A missing directory raises ArgumentError naming the path.

Source

Thrown at lib/puppet/pal/pal_impl.rb:300

                          env_dir:       nil,
                          envpath:       nil,
                          facts:         nil,
                          variables:     {},
                          &block)
    # TRANSLATORS terms in the assertions below are names of terms in code
    assert_non_empty_string(env_name, 'env_name')
    assert_optionally_empty_array(modulepath, 'modulepath', true)
    assert_optionally_empty_array(pre_modulepath, 'pre_modulepath', false)
    assert_optionally_empty_array(post_modulepath, 'post_modulepath', false)
    assert_mutually_exclusive(env_dir, envpath, 'env_dir', 'envpath')

    unless block_given?
      raise ArgumentError, _("A block must be given to 'in_environment'") # TRANSLATORS 'in_environment' is a name, do not translate
    end

    if env_dir
      unless Puppet::FileSystem.exist?(env_dir)
        raise ArgumentError, _("The environment directory '%{env_dir}' does not exist") % { env_dir: env_dir }
      end

      # a nil modulepath for env_dir means it should use its ./modules directory
      mid_modulepath = modulepath.nil? ? [Puppet::FileSystem.expand_path(File.join(env_dir, 'modules'))] : modulepath

      env = Puppet::Node::Environment.create(env_name, pre_modulepath + mid_modulepath + post_modulepath)
      environments = Puppet::Environments::StaticDirectory.new(env_name, env_dir, env) # The env being used is the only one...
    else
      assert_non_empty_string(envpath, 'envpath')

      # The environment is resolved against the envpath. This is setup without a basemodulepath
      # The modulepath defaults to the 'modulepath' in the found env when "Directories" is used
      #
      if envpath.is_a?(String) && envpath.include?(File::PATH_SEPARATOR)
        # potentially more than one directory to search
        env_loaders = Puppet::Environments::Directories.from_path(envpath, [])
        environments = Puppet::Environments::Combined.new(*env_loaders)
      else

View on GitHub (pinned to e227c27540)

Solutions

1. Verify the path: File.directory?(File.expand_path(env_dir)) before calling
2. Create the directory (and its modules/ layout) or fix the typo
3. Pass an absolute path, or use envpath pointing at the parent of the environments tree

Example fix

# before
Puppet::Pal.in_environment('prod', env_dir: 'environments/prod')

# after
env_dir = File.expand_path('spec/fixtures/environments/prod', __dir__)
raise ArgumentError, "missing #{env_dir}" unless File.directory?(env_dir)
Puppet::Pal.in_environment('prod', env_dir: env_dir) { |pal| }

env_dir = File.expand_path(env_dir)
raise ArgumentError, "env_dir #{env_dir} not found" unless File.directory?(env_dir)

When it happens

Trigger: Puppet::Pal.in_environment('prod', env_dir: '/nonexistent/environments/prod'); relative paths that resolve against an unexpected cwd; fixture directories never created in tests.

Common situations: Path typos; running the tool on a different machine than the Puppet code lives on; test specs that assume spec/fixtures was generated; relative vs absolute path confusion.

Related errors

• No directory found for the environment '%{env_name}' on the
• Invalid environment mode '%{mode_name}'
• Could not destroy %{json} %{request}: %{detail}
• Could not read JSON data for %{name} %{key}: %{detail}
• Could not destroy %{name} %{request}: %{detail}

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/6cb819e2d4ea7f5b. Report an issue: GitHub.