Run the bolt task show command or Get-BoltTask PowerShell cmdlet and look for any warnings related to your task metadata.

Make sure your task name is valid: Task names must

• Be lowercase

• Start with a letter

• Can only contain letters, numbers and underscores

Make sure your task executable is named the same as your task metadata. For example, if your task is named mytask.rb, you must name your metadata file mytask.json.

If you receive the following error:

Unable to use command 'bolt module add'. To use this command, update your project configuration to manage module dependencies.

You need to upgrade your project so Bolt can manage your modules and dependencies. For more information, see migrate a Bolt project.

If your task fails with the following error, the issue might be that your temporary directory (tmpdir) is mounted with noexec.

The task failed with exit code 126 and no stdout but stderr contained: 
.... <temp path to task>>.rb: Permission denied

You can resolve this by configuring an alternate tmpdir for the transport you're using, or by talking to your administrator about updating permissions for the directory.

Try running Bolt with --log-level debug to see the exact output from your task.

Make sure your task executable starts with a shebang (#!) line indicating the interpreter to use and verify that the executable is present on the target system. For example, if you write a Python task and include the line: #!/usr/bin/env python, Bolt attempts to execute the script using the default python executable on the target system.

Bolt does not support PowerShell 2.0. If your task targets a Windows OS that has only PowerShell 2.0 installed, the task will fail.

In 2017, Microsoft deprecated PowerShell 2.0. For a more detailed explanation, see Micosoft's blog post on the subject.

Both Microsoft and Puppet recommend updating the target with Windows PowerShell 5.1, but versions 3.0 and 4.0 are also supported.

The default log level for the console is warn. If you use a notice function in a plan, Bolt does not print it to the console. When you have messages you want to be printed to the console regardless of log level you should use the out::message plan function. The out::message function is not available for use in an apply block and only accepts string values.

If you need to send a message that is not a string value or is in an apply block, you can use the warning Puppet log function.

If you only wish to see the output in the console when executing your plan with the --log-level debug command-line option, use the notice Puppet log function. The notice function sets the console log level to debug for that run.

For more information, see the docs for configuring Bolt's log level.

If you see a gem related error similar to the following:

    Ignoring nokogiri-1.10.2 because its extensions are not built. Try: gem pristine nokogiri --version 1.10.2
    Ignoring unf_ext-0.0.7.5 because its extensions are not built. Try: gem pristine unf_ext --version 0.0.7.5

Use the Bolt-provided gem command to reinstall/install these gems. For example:

    sudo /opt/puppetlabs/bolt/bin/gem pristine nokogiri --version 1.10.2
    sudo /opt/puppetlabs/bolt/bin/gem pristine unf_ext --version 0.0.7.5

When running on Windows, Bolt automatically sets the SSL_CERT_DIR and SSL_CERT_FILE environment variables if they are not already set. Assuming a default install location, the variables are set to the following directory and certificate, which are installed with the Bolt package:

• SSL_CERT_DIR = C:\Program Files\Puppet Labs\Bolt\ssl\certs

• SSL_CERT_FILE = C:\Program Files\Puppet Labs\Bolt\ssl\cert.pem

If you see an SSL connection error similar to the following when running on Windows:

SSL_connect returned=1 errno=0 state=error: certificate verify failed (unable to get local issuer certificate)

Set the SSL_CERT_DIR and SSL_CERT_FILE environment variables to use a valid certificate and certificate directory.

Visit the #bolt channel in the Puppet Community Slack to find a whole community of people waiting to help!

PowerShell 3.0 cannot automatically discover and load the Bolt module. If you're using PowerShell 3.0, add the Bolt module manually.

🔩 Tip To confirm your PowerShell version, run$PSVersionTable.

To allow PowerShell to load Bolt, add the correct module to your PowerShell profile.

1. Update your PowerShell profile.

   'Import-Module -Name ${Env:ProgramFiles}\WindowsPowerShell\Modules\PuppetBolt' | Out-File -Append $PROFILE

2. Load the module in your current PowerShell window.

   . $PROFILE

PowerShell's execution policy is a safety feature that controls the conditions under which PowerShell loads configuration files and runs scripts. This feature helps prevent the execution of malicious scripts. The default policy is Restricted (allow no scripts to run) for Windows clients and RemoteSigned (allow signed scripts and non-signed scripts not from the internet) for Windows servers. Some environments change this to AllSigned, which only allows scripts to run as long as they are signed by a trusted publisher.

As of Bolt 2.21.0, we sign Bolt PowerShell module files with a Puppet code signing certificate. If your PowerShell environment uses an AllSigned execution policy and you add Puppet as a trusted publisher, the bolt command works without any further input. If you're using the AllSigned policy and you have not added Puppet as a trusted publisher, you can accept the publisher without having to change your execution policy.

If your environment uses a Restricted policy, you must change your policy to RemoteSigned or AllSigned. Check with your security team before you make any policy changes.

If you see this or a similar error when trying to run Bolt, you probably need to change your script execution policy restrictions:

bolt : The 'bolt' command was found in the module 'PuppetBolt', but the module could not be loaded. 
For more information, run 'Import-Module PuppetBolt'.
                At line:1 char:1
                + bolt --help
                + ~~~~
                + CategoryInfo          : ObjectNotFound: (bolt:String) [], CommandNotFoundExceptio
                n
                + FullyQualifiedErrorId : CouldNotAutoloadMatchingModule

To change your script execution policy:

1. Press Windows+X, A to run PowerShell as an administrator.

2. Set your script execution policy to at least RemoteSigned:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

   For more information about PowerShell execution policies, see Microsoft's documentation about execution policies and how to set them.