Troubleshooting Windows

Troubleshoot issues in Windows PE installations, such as failed installations, failed upgrades, problems applying manifests, and other issues.

If you are experiencing failures when installing or upgrading agents, refer to Installation fails and Upgrade fails.

If manifests are failing to be applied, or are being applied incorrectly, refer to Errors when applying a manifest or doing a Puppet agent run.

For other issues, refer to the Error messages reference. You might need to enable temporary Logging and debugging.

Installation fails

Check for these issues if Puppet agent installation fails on a Windows node.

The installation package isn't accessible

The source of an .msi or .exe package must be a file on either:
  • A local filesystem
  • A network mapped drive
  • A UNC path

RI-based installation sources aren't supported, but you can achieve a similar result by defining a file whose source is the primary server, and then defining a package whose source is the local file.

Installation wasn't attempted with admin privileges

Installing thePuppet agent requires elevated privileges, such as being logged in as the Administrator or running commands in an Administrator command prompt or PowerShell window.

The following are indications that you are attempting to install without admin privileges:
  • Agent installation fails when trying to perform an unattended installation from the command line.
  • You get a norestart message.
  • The installation logs indicate that installation is forbidden by system policy.

Upgrade fails

The Puppet agent .msi package overwrites existing entries in the puppet.conf file. If you upgrade or reinstall the agent with a different primary server hostname, Puppet applies the new value in $confdir\puppet.conf file.

When you upgrade a Windows agent, you must use the same primary server hostname that you specified when you originally installed the agent.

For information on configuring puppet.conf and which settings are preserved during upgrades, refer to MSI properties.

Errors when applying a manifest or doing a Puppet agent run

If your manifests aren't applied, or are applied incorrectly, on Windows nodes, check for these issues.

Path or file separators are incorrect

For Windows nodes, path separators must use a semi-colon (;).

File separators must use forward slashes or backslashes, depending on the attribute. In most resource attributes, the Puppet language accepts either forward slashes or backslashes as the file separator. However, some attributes absolutely require forward slashes, and some attributes absolutely require backslashes.

You must escape backslashes that are double-quoted("). When single-quoted ('), escaping is optional. For example, these are all valid file resources:
file { 'c:\path\to\file.txt': }
file { 'c:\\path\\to\\file.txt': }
file { "c:\\path\\to\\file.txt": }

However file { "c:\path\to\file.txt": } is an invalid path, because \p, \t, and \f are interpreted as escape sequences.

For more information:

Cases are inconsistent

Several resources are case-insensitive on Windows, like files, users, groups. However, these resources can be case sensitive in Puppet.

When establishing dependencies among resources, make sure to specify the case consistently. Otherwise, Puppet can't resolve the dependencies correctly. For example, Puppet fails to apply the following manifest because it doesn't recognize that ALEX and alex are the same user:
file { 'c:\foo\bar':
  ensure => directory,
  owner  => 'ALEX'
}
user { 'alex':
  ensure => present
}
...
err: /Stage[main]//File[c:\foo\bar]: Could not evaluate: Could not find user ALEX

Shell built-ins are not executed

Puppet doesn't support a shell provider on Windows, so executing shell built-ins directly fails.

To troubleshoot this, use cmd.exe to wrap the built-in:
exec { 'cmd.exe /c echo foo':
  path => 'c:\windows\system32;c:\windows'
}
Tip: In the 32-bit versions of the Puppet agent, you might encounter file system redirection, where system32 is automatically switched to sysWoW64.

PowerShell scripts are not executed

By default, PowerShell enforces a restricted execution policy that prevents executing scripts.

To avoid this, use the Puppet-supported PowerShell or specify the appropriate execution policy in the PowerShell command, for example:
exec { 'test':
  command => 'powershell.exe -executionpolicy remotesigned -file C:\test.ps1',
  path    => $::path
}

Services are referenced by display names instead of short names

Windows services support a short name and a display name, but Puppet uses only short names.

Verify that your Puppet manifests use the short names, such as wuauserv instead of Automatic Updates.

Error messages

These are some error messages you might encounter when using Puppet on Windows nodes.

Forge connection or SSL certificate errors
Errors include Could not connect via HTTPS to https://forge.puppet.com, Unable to verify the SSL certificate, The certificate may not be signed by a valid CA, and The CA bundle included with OpenSSL may not be valid or up to date.
These errors occurs when you run the puppet module subcommand on newly provisioned Windows nodes. The Forge uses an SSL certificate signed by the GeoTrust Global CA certificate, and new Windows nodes might not have that CA in their root CA store yet.
Download the GeoTrust Global CA certificate from GeoTrust's list of root certificates, and then manually install it on the agent node by running: certutil -addstore Root GeoTrust_Global_CA.pem
Service 'Puppet Agent' (puppet) failed to start. Verify that you have sufficient privileges to start system services.
This error occurs when installing Puppet on a UAC system from a non-elevated account. Although the installer displays the UAC prompt to install Puppet, it does not elevate privileges when trying to start the service.
Make sure to run the .msi installation from an elevated cmd.exe process. For more information, refer to Commands with elevated privileges.
Cannot run on Microsoft Windows without the <GEM_NAME> gem.
This error occurs if you attempt to run Windows without required gems.
Required gems include: sys-admin, win32-process, win32-dir, win32-service and win32-taskscheduler
Run this command to install the specified gems: gem install <GEM_NAME>
/Stage[main]//Scheduled_task[task_system]: Could not evaluate: The operation completed successfully.
This error occurs when the task scheduler gem has a version earlier than 0.2.1.
Run this command to update the task scheduler gem: gem update win32-taskscheduler
/Stage[main]//Exec[C:/tmp/<FILE_NAME>.exe]/returns: change from notrun to 0 failed: CreateProcess() failed: Access is denied.
This error occurs when a request for an executable on a remote primary server can't be executed.
Make sure the user and group executable bits are set appropriately on the primary server, for example:
file { "C:/tmp/<FILE_NAME>.exe":
  source => "puppet:///modules/<FOLDER_NAME>/<FILE_NAME>.exe",
}

exec { 'C:/tmp/<FILE_NAME>.exe':
  logoutput => true
}
getaddrinfo: The storage control blocks were destroyed.
This error occurs when the agent can't resolve a DNS name into an IP address or if the agent has an incorrect reverse DNS entry.
Verify that you can run nslookup <DNS>. If this fails, there is a problem with the DNS settings on the Windows agent. For example, the primary DNS suffix might not be set. For more information, refer to Microsoft's DNS documentation.
Could not request certificate: The certificate retrieved from the primary does not match the agent's private key.
This error can occur if the agent is running in two different security contexts or if the agent's SSL directory is deleted after it retrieves a certificate from the primary server.
Make sure you elevate privileges by selecting Run as Administrator when you select Start Command Prompt with Puppet.
Could not send report: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed. This is often because the time is out of sync on the server or client.
This error occurs when time on the Windows agents isn't synchronized.
Windows agents that are part of an Active Directory (AD) domain automatically have their time synchronized with AD.
For agents that are not part of an AD domain, you must run the following commands to manually enable and add the Windows time service:
w32tm /register
net start w32time
w32tm /config /manualpeerlist:<NTP_SERVER> /syncfromflags:manual /update
w32tm /resync
Could not parse for environment production: Syntax error at '='; expected '}'
This error occurs if you run puppet apply -e from the command line, and the supplied command is surrounded with single quotes ('). The single quotes cause cmd.exe to interpret any rocket hash (=>) in the command as a redirect.
Retry the command with double quotes (") instead of single quotes.

Logging and debugging

The Windows Event Log can be helpful when troubleshooting issues with Windows nodes.

To enable the Puppet agent to emit --debug and --trace messages to the Windows Event Log, run this command to stop and restart the Puppet service: 
c:\>sc stop puppet && sc start puppet --debug --trace
Restriction: This setting applies only until the next time the service is restarted or the system is rebooted.