Troubleshooting · 15.4
Deployment targets
A failed deployment is logged as event 1302, a failed Health check as event 1322. The tab Helper of a deployment lists the requirements of the target, for example for WinRM. Use Test (dry run)… in the deployment to check the settings before you deploy.
| Symptom | Cause | Solution |
|---|---|---|
| All targets | ||
| … requires PFX bytes (private key missing on this management host). or … requires PEM certificate and private key | The target needs the private key, but it is not kept on the management host (column Key shows –). | Renew the certificate with Force renew… so that the new version keeps its private key on the management host, then deploy again. |
| Deployment setting <key> is required. or <Target> requires settings.<key> | A required field of the deployment is empty. | Open the deployment and fill in the fields marked with *. |
| Health: … thumbprint is <thumbprint>, expected <thumbprint> or … is not bound to … | The target uses another certificate, or the certificate was uploaded but not bound. | Deploy again. For targets with manual bindings, bind the certificate on the target. |
| Certificate CN/SAN does not match hostname <host> | The name used for the target is not contained in the certificate. | Add the name to the certificate or use a name of the certificate for the target. |
| Windows (WinRM): certificate store, IIS, RDS, Exchange, AD FS, SQL Server, NPS, File Path, UNC | ||
| Remote probe to <host> requires a WinRM credential. or Credential <name> is missing or incomplete. | No WinRM credential is selected for a remote Windows target. | Select a credential with access to the target. |
| WinRM PowerShell timed out after <n>s. | The target does not answer via WinRM. | Check the tab Helper: Enable-PSRemoting -Force -SkipNetworkProfileCheck on the target, inbound WinRM in the firewall (TCP 5986 for HTTPS and/or TCP 5985 for HTTP) and TrustedHosts on the management host with the same host string as in the deployment. |
| IIS site <site> not found. | The website name does not exist on the IIS server. | Enter the name of the website exactly as shown in IIS Manager. |
| UNC path must start with \\ (e.g. \\fileserver\certs). | The UNC path has the wrong format. | Use the form \\server\share\folder. |
| Linux (SSH): Nginx, Apache, HAProxy, Tomcat, PostgreSQL, MySQL/MariaDB, File Path | ||
| SSH credential <name> not found. | No SSH credential is selected or it was deleted. | Select an SSH credential of the type Linux SSH (Nginx / Apache), see chapter Nginx. |
| certPath and keyPath must be absolute Unix paths (start with /). | A relative path was entered. | Enter absolute paths, for example /etc/nginx/ssl/site.crt. |
| Health: Certificate file may be present but it is not bound in the live service config. | The file was written, but the service configuration does not use it. | Point the configuration of the service to the file and reload the service. |
| File targets and export: File Path (WinRM), UNC share, File Path (SSH), Export certificate | ||
| Warning: The root certificate was not in the stored chain and was not found on this management host. The file was written without the root. | Include root is on, the CA did not deliver the root in the chain, and the root is neither in Trusted Root Certification Authorities nor in Intermediate Certification Authorities of the management host (computer or current user). TLSPilot does not download the root and does not look on the target. | Usually nothing: clients have the root in their root store, and the standard order omits it. If the receiving system really needs the root, import the root certificate of the CA into Cert:\LocalMachine\Root on the management host and export or deploy again, see chapter Chain options. |
| PFX export could not build the certificate chain. The file was not written. | PFX with Include chain on: the private key or the certificate is not available on the management host, the key does not match any certificate in the chain, or the PFX could not be built. TLSPilot does not write an incomplete file; a deployment fails (event 1302). | Check that the column Key of the certificate shows a stored key; if not, renew with Force renew… so that the key is kept on the management host. Then export or deploy again. If the key is stored and the error remains, switch off Include chain for this target as a workaround; the PFX then contains only the certificate and the key, see chapter Standard order of the chain. |
| ADC and firewalls: F5 BIG-IP, Palo Alto | ||
| Palo Alto partial commit failed: or Partial commit finished but running config does not match | The commit on the firewall did not complete. | Check pending changes and commit locks on the firewall, then deploy again. |
| Cloud: Azure, Entra ID, Google Cloud, AWS, Omnissa UAG | ||
| Classic Front Door is not supported. Use a Standard or Premium profile. Classic ends on March 31, 2027. or Front Door SKU is '<sku>'. Only Standard_AzureFrontDoor and Premium_AzureFrontDoor are supported. or Front Door does not accept ECC certificates. Use RSA. | Azure Front Door (classic) or an ECC key is used. | Use a Front Door Standard or Premium profile and an RSA key. |
| No application found for appId <id> | The app registration does not exist in the tenant, or the credential may not read it. | Check the Application ID and the permissions of the credential. |
| AWS ACM <action> failed (<status>), Azure Key Vault requires settings.vaultName or vaultUri. | The cloud API rejected the call, or a required field is empty. | Check the fields of the deployment and the permissions of the credential in the cloud. |
| Custom Deployment | ||
| Custom Deployment requires a PowerShell script (settings.script). or Custom script is empty. | No script is stored in the deployment. | Add a script, for example one of the example scripts, see chapter Custom Deployment. |