Troubleshooting

This page organizes general checks by deployment stage. Error messages and exit codes can change by release. Record the actual command, exact time, and sanitized logs instead of substituting messages from another version.

Installation

The binary does not run:

Confirm that the downloaded platform and architecture match the server. Use uname -m to inspect architecture.
On Linux or macOS, confirm that you ran chmod 755.
Verify SHA256 against the download page to rule out a corrupted download.
On Windows, inspect the Unblock option in file properties if the system reports that the file is blocked.

--help returns no output or an error: the file may be incomplete or built for another platform. Download it again and verify the checksum.

login initialization fails:

Confirm that the Endpoint is correct and reachable from the server, including outbound firewall and proxy rules.
Re-enter AccessKey and AccessSecret, checking for whitespace introduced during copy and paste.
Confirm in the upstream console that the credentials remain valid and have not been revoked.

Login succeeds but the node is unavailable: confirm that the node was activated in the CaaS management console. See Configuration.

Authentication and connection checks for a private CLM or another certificate service depend on its adapter. Review the adapter documentation, upstream API logs, and network policy together.

Certificate discovery

discover-certificate finds no certificate or misses some certificates:

Confirm that the clmbot account can read the certificate paths. See Least privilege.
Scan scope depends on release, operating system, and permissions. Check the path and account permissions first, then follow configuration generated by the same release if a manual entry is needed. See Certificate discovery.

config.yaml was not generated: confirm that you entered Y after reviewing the scan results and that clmbot can write to the runtime directory.

Updates

The certificate did not change after update-certificate:

Confirm that the upstream actually issued a new certificate. With CaaS, inspect reissuance status and the configured period.
Check certificate paths and format values in servers[].
Confirm that the clmbot account can write the certificate files and directory and create .bak backups.
Inspect output for this run in update.log.

The scheduled task did not run:

Linux: verify that the crontab belongs to the clmbot account, the schedule is valid, and the command changes to the runtime directory first.
Windows: inspect the last Task Scheduler result and verify the working directory, runtime account, and Run whether user is logged on or not setting.

Service reloads

The certificate file changed, but the service still presents the old certificate:

Confirm that after_script exists and contains the correct command, such as nginx -t && nginx -s reload.
Run the after_script command manually under the clmbot account and check for a missing exact sudoers rule. See Least privilege.
For Tomcat, confirm that the script controls the correct instance.
If reload fails, restore the .bak file manually. See Automatic updates and service reloads.

Log locations

Update log: update.log in the runtime directory. Scheduled-task examples append command output with >> update.log.
Inspect logs regularly to confirm that each update completes.
When a process manager hosts Server mode, also inspect standard output and error collected by systemd, Windows Services, or the container platform.

Still unresolved?

Ask a usage question in GitHub Discussions or file a reproducible bug in GitHub Issues. See Get help.
Sanitize before posting: remove AccessKey, AccessSecret, private keys, internal IP addresses, hostnames, and complete certificate contents. Use the checklist in Security.
Do not report a vulnerability publicly. Use the private channel described in Security.

Automatic updates and service reloads: the update workflow
Configuration reference: fields and commands
Get help: support routing