PDK troubleshooting

If you are encountering trouble with PDK, check for these common issues. 

Feedback on PDK documentation

If you don’t see what you need, if something isn't clear enough, or if you spot a mistake in PDK documentation, let our documentation team know by opening a ticket (you'll need a Jira account). Be specific about the request or issue so that our team can help update the documentation. We greatly appreciate your feedback!

PDK not in ZShell PATH on macOS X

With ZShell on macOS X, PDK is not automatically added to the PATH. To fix this, add the PATH by adding the line eval (/usr/libexec/path_helper -s) to the ZShell resource file (~/.zshrc).

PDK failing to pull from custom git server

If a fatal: unable to access...SSL certificate problem: self signed certificate error occurs during PDK usage, it indicates that the PDK is trying to download a module from a source that isn't trusted. For example, given a .fixtures.yml that references an untrusted self-hosted git repository server git.self.hosted

# .fixtures.yml
        ---
fixtures:
  forge_modules:
    nginx: "puppet/nginx"
  repositories:
    mymodule: 'https://git.self.hosted/companyxyz/mymodule.git'

then running pdk test unit will throw an error something like:

root@seattle:~/modules/tester# pdk test unit
pdk (INFO): Using Ruby 3.2.2
pdk (INFO): Using Puppet 8.1.0
[✖] Preparing to run the unit tests.
[✔] Cleaning up after running unit tests.
pdk (ERROR): The spec_prep rake task failed with the following error(s):
Cloning into 'spec/fixtures/modules/mymodule'...
fatal: unable to access 'https://git.self.hosted/companyxyz/mymodule.git/': SSL certificate problem: self signed certificate
#<Thread:0x00007ffff9b2e138 /opt/puppetlabs/pdk/share/cache/ruby/3.2.0/gems/logging-2.3.1/lib/logging/diagnostic_context.rb:471 run> terminated with exception (report_on_exception is true):
...
...

To resolve this issue, first create a backup of the existing PDK certificates file, which lives in /opt/puppetlabs/pdk/ssl/cert.pem on Linux machines and C:\Program Files\Puppet Labs\DevelopmentKit\ssl\cert.pem on Windows.

Then do the following:

Obtain the chain of trust certificates from the self-hosted server. For example, printf '' | openssl s_client -connect git.self.hosted:443 -showcerts will return metadata including the trust certificates for the git.self.hosted:443 server.

Append the trust certificates to the end of the cert.pem ensuring the pdk trusts the new self-hosted git server.