puppetlabs/puppet · error · Puppet::Error

A project name must be specified in order to initialize tran

Error message

A project name must be specified in order to initialize translations.

What it means

Puppet::GettextConfig.load_translations binds a FastGettext repository for a named project (project_name) under a locale directory. It refuses nil or empty project names because gettext cannot register an anonymous repository, raising Puppet::Error before any filesystem or format work happens.

Source

Thrown at lib/puppet/gettext/config.rb:230

      :po
    end
  end

  # @api private
  # Prevent future gettext initializations
  def self.disable_gettext
    @gettext_disabled = true
  end

  # @api private
  # Attempt to load translations for the given project.
  # @param [String] project_name the project whose translations we want to load
  # @param [String] locale_dir the path to the directory containing translations
  # @param [Symbol] file_format translation file format to use, either :po or :mo
  # @return true if initialization succeeded, false otherwise
  def self.load_translations(project_name, locale_dir, file_format, text_domain = FastGettext.text_domain)
    if project_name.nil? || project_name.empty?
      raise Puppet::Error, "A project name must be specified in order to initialize translations."
    end

    return false if @gettext_disabled || !@gettext_loaded

    return false unless locale_dir && Puppet::FileSystem.exist?(locale_dir)

    unless file_format == :po || file_format == :mo
      raise Puppet::Error, "Unsupported translation file format #{file_format}; please use :po or :mo"
    end

    add_repository_to_domain(project_name, locale_dir, file_format, text_domain)
    true
  end

  # @api private
  # Add the translations for this project to the domain's repository chain
  # chain for the currently selected text domain, if needed.
  # @param [String] project_name the name of the project for which to load translations

View on GitHub (pinned to e227c27540)

Solutions

Pass the real project name under which the .po files are compiled (e.g. 'puppet' or 'puppet-agent').
Prefer puppet's own initialization (Puppet::GettextConfig.load_default_text_domain or full Puppet initialization) instead of calling load_translations directly.
Check the caller's stack to find which code path supplies the nil name if it is not obvious.

Example fix

# before
Puppet::GettextConfig.load_translations(nil, locale_dir, :po)

# after
Puppet::GettextConfig.load_translations('puppet', locale_dir, :po)

Defensive patterns

Strategy: validation

Validate before calling

project = project_name.to_s
raise ArgumentError, 'project_name required' if project.empty?
Puppet::GettextConfig.load_translations(project, locale_dir, :po)

Prevention

Do not call translation internals directly; use puppet's normal initialization.
Fail fast on nil config values at your own entrypoint instead of forwarding them.

When it happens

Trigger: Calling Puppet::GettextConfig.load_translations(nil, dir, :po) or load_translations('', dir, :mo) — typically from custom entrypoints that embed puppet (gems, packaging scripts, puppetserver-side wrappers) and skip puppet's normal initialization, or from specs that stub the gettext config with nil.

Common situations: Downstream distributions wiring their own translation setup; test helpers passing a variable that was never assigned; refactors where the project name constant was dropped; JRuby hosts initializing puppet partially.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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