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.
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!