Debugging common Bolt errors
Bolt can’t find my task
Run bolt task show
and look for any warnings related to your task metadata.
Make sure your task name is valid. Task names must be lowercase, must start with a letter, and can only contain letters, numbers and underscores.
Make sure your task executable is named same as your task metadata, ie. mytask.rb
and mytask.json
.
My task fails mysteriously
Make sure your task executable starts with a #!
line indicating the interpreter to use and verify that the executable is present on the target system.
Try running Bolt with --debug
to see the exact output from your task.
Bolt can’t connect to my hosts over SSH
Host key verification failures
When connecting over SSH, Bolt checks the host key against the fingerprint in ~/.ssh/known_hosts
to verify the host is the one it’s expecting to connect to.
This will show up as an error like the following:
fingerprint SHA256:6+fv7inQSgU2DuYF5NolTlGF6xM8RBRTw1W6B9rbHkc is unknown for "hostname.example.com,10.16.112.82"
This error means that there is no key for the host in ~/.ssh/known_hosts
, so Bolt doesn’t know how to tell if it’s the right host.
If you can connect to the host over SSH outside Bolt, you can store the SSH host key fingerprint with ssh-keyscan hostname.example.com >> ~/.ssh/known_hosts
.
You can disable this check entirely with --no-host-key-check
on the CLI or the host-key-check: false
option under the ssh
section of bolt.yaml
. Note that doing so will reduce the security of your SSH connection.
Timeout or connection refused
By default, Bolt tries to connect over the standard SSH port 22. If you need to connect over a different port, either include in the name of the target (hostname.example.com:2345
) or set it in your Bolt config or inventory.
Bolt can’t connect to my Windows hosts
Timeout or connection refused
Make sure you’ve specified the winrm
protocol for the target. You can either include it in the name of the target (winrm://hostname.example.com
), pass --transport winrm
on the CLI, or set the transport in your Bolt config or inventory. By default, Bolt will try to connect over SSH.
Puppet log functions are not logging to the console
The default log level for the console is warn
. When a notice
function is used in a plan, it will not be printed 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. The notice
Puppet log function could be used when you only wish to see the output in the console when executing your plan with the --debug
flag which will set the console log level to debug
for that run.
See the docs for configuring the Bolt’s log level for more information about how to configure the log levels.
‘Extensions are not built’ error message
Either after installation, upgrade, or environmental changes you may receive error messages when launching Bolt.
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
To correct this issue you will need to use the Bolt provided gem command to reinstall/install these gems.
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
I still need help
Visit the #bolt channel in the Puppet Community Slack and you will find a whole community of people waiting to help!