Troubleshooting

Where to start

Start with the error shown in the terminal or container logs. Use the same account, configuration path and --env setting as the running agent. Stop at the first failed check and fix it before trying deployment again.

What you see	Start here
Command missing or cannot start	certone version; check installation and PATH
Configuration error	certone check; use the named field or environment variable in the error
No certificates or connection problem	certone doctor --network; check the listed certificate IDs
Deployment or reload failure	Read the target and error in logs; inspect certone status
Website still serves the old certificate	Verify its configured file paths, hostname and actual HTTPS endpoint

For a deeper investigation, identify the failing stage:

1. Can the program run? Run certone version and confirm the OS and architecture.
2. Can it read the configuration? Run check and inspect the configuration path, fields, and credentials.
3. Can it connect to the platform? Run doctor --network to distinguish network errors from authentication rejection.
4. Are the correct certificates available? Check platform node associations, certificate IDs, and valid versions.
5. Were certificates written or imported? Inspect the target name and failure stage, then check permissions, directories, or API access.
6. Did the application load them? Check validation/reload commands, IIS bindings, or DSM service assignments.
7. Are you visiting the same endpoint? Rule out a CDN, load balancer, another replica, or incorrect SNI.

check and doctor --network are diagnostic tools, not deployment tests. Before running sync --once, stop any persistent process using the same state directory.

Diagnostic commands

For a local installation using the default configuration, run as the actual runtime account:

certone version
certone check
certone doctor --network
certone status

The local wizard defaults to ~/.certone/logs/certone.log. On Linux/macOS, use tail -n 100 "$HOME/.certone/logs/certone.log". On Windows, use Get-Content "$env:USERPROFILE\.certone\logs\certone.log" -Tail 100.

If an administrator runs the service, reading its protected files also requires the appropriate permissions. Linux/macOS example:

sudo "$(command -v certone)" status --config "$HOME/.certone/config.yaml"
sudo tail -n 100 "$HOME/.certone/logs/certone.log"

Here, sudo allows access to administrator-owned configuration, state, and logs. Replace a custom configuration location with its actual absolute path.

For Docker environment-variable mode, replace my-app with the container name:

docker logs --tail 100 my-app
docker exec my-app certone check --env
docker exec my-app certone doctor --network --env
docker exec my-app certone status --env

If the container uses a configuration file, use --config /actual/path/config.yaml instead. On Windows, inspect service status with Get-Service certone. For IIS deployment failures, also inspect the website binding and local machine certificate store.

Error reference

Error or symptom	Possible cause	What to do
CONFIG_NOT_FOUND	No configuration at the displayed path, sometimes because sudo changed the runtime user	Run certone init, or pass the existing file with --config; do not initialize a second configuration accidentally
CONFIG_INVALID or YAML parsing error	Misspelled fields, indentation, duplicate paths, or invalid values	Check the configuration reference and run check; do not add unsupported fields
PATH_NOT_WRITABLE / LOG_UNWRITABLE	Runtime account cannot write the named directory or log	Grant that account the required permissions, or choose a writable destination; if service files are root-owned, run maintenance as that service account
COMMAND_NOT_FOUND / COMMAND_DIRECTORY	Incorrect application executable or working directory	Correct the named target command; on Debian/Ubuntu, Apache commonly uses apache2ctl rather than httpd
DIAGNOSE_EXISTS	The chosen report file already exists	Choose a new --output filename; existing files are never overwritten
AUTH_INVALID	Node ID and Token do not match	Correct the credentials and restart; authentication retries will not resume automatically
NODE_DISABLED	Node is disabled or deleted	Check the node in the platform, restore it, and restart
CONNECT_TIMEOUT or DISCONNECTED	Network, DNS, TLS, proxy, or firewall failure	Check the platform URL and outbound connectivity, including WebSocket access; deleting state will not fix this
STATE_LOCKED	Another process uses this directory, or the lock directory is inaccessible	Check services, foreground processes, and directory permissions; do not delete the lock to bypass a running process
INSTANCE_CONFLICT	Multiple processes copied the same instance identity	Stop duplicate instances; use a separate empty state directory for each new replica
STATE_NODE_MISMATCH	A different node ID is being used with existing state	Use separate state directories for different nodes
STATE_CORRUPT	State file is damaged or manually modified	Stop the process, preserve logs and files, and restore a consistent backup or contact support; do not clear state arbitrarily
CERT_MISSING / CERT_FORBIDDEN	Incorrect certificate ID, node association, or available version	Check associations and certificate status in the platform; a domain name is not a certificate ID
TARGET_NOT_CONFIGURED	A certificate was fetched but no local deployment mapping uses it	For ordinary file deployment, use an automatic template without id; for IIS, check the site's hostname mapping
CERT_NONE_BOUND	The node has no associated, issued, valid certificates	Associate certificates in the platform and run sync --once; a persistent agent checks again on a push or later synchronization
CERT_SELECTION_AMBIGUOUS	An IIS or TLS verification endpoint matches zero or multiple certificates	Check the hostname and node associations, or configure an explicit mapping for the target
TARGET_AMBIGUOUS	Multiple certificates point to one DSM entry or default-certificate slot	Use a description template containing {id} with as_default disabled, or configure explicit mappings separately
CERT_INVALID / CERT_DOMAIN_MISMATCH	Invalid certificate, private key, chain, validity period, or domain coverage	Check system time, certificate status, and domains; do not bypass validation
COMMAND_NOT_FOUND	Incorrect executable path	Use an absolute path and distinguish host paths from container paths
PATH_UNSAFE / DEPLOY_WRITE_FAILED	Output is a directory or symlink, parent is unwritable, single-file mount, or disk problem	Use a regular file path with a writable parent; check free space, read-only mounts, and permissions
CHECK_FAILED	Application configuration validation failed	Read command output, run the same check as the same account, and fix application configuration
RELOAD_FAILED / COMMAND_FAILED	Application is stopped, permissions are insufficient, or command failed	Check the PID, service status, and correct reload procedure
COMMAND_TIMEOUT	Command is slow, waiting for input, or does not exit	Resolve blocking behavior first; increase its timeout only if needed
VERIFY_FAILED / VERIFY_CA_INVALID	Wrong certificate, untrusted TLS, or incorrect address, port, or SNI	Connect to the actual application endpoint and check the hostname, CA file, and certificate validity
ROLLBACK_FAILED / ROLLBACK_RELOAD_FAILED / RECOVERY_REQUIRED	File or application recovery is incomplete	Preserve backups and recovery records, resolve permission, disk, or service errors, then allow recovery
BOOTSTRAP_FAILED	Startup could not obtain usable certificates and the cache is unusable	Check platform connectivity, associations, and cache validity; the first startup must obtain certificates
DSM_NETWORK / DSM_HTTP / DSM_API_ERROR	DSM address, TLS, permissions, or login requirements are not satisfied	Diagnose from the same container network and check return codes, account permissions, and MFA
DSM_CERT_NOT_FOUND / DSM_TARGET_AMBIGUOUS	ID does not exist or the description is not unique	Select an exact ID or unique description; enable create only when creation is intended
IIS_PLATFORM / IIS_PREREQUISITE	Non-Windows environment or missing tools	Run on Windows with Windows PowerShell and IIS management components
IIS_BINDING_NOT_FOUND_OR_AMBIGUOUS	HTTPS binding cannot be matched uniquely	Check site name, IP, port, and hostname; create the correct binding first
IIS_CCS_UNSUPPORTED	Binding uses Central Certificate Store	This binding type is unsupported; arrange another deployment method
IIS_RECOVERY_REQUIRED	Binding target changed during an interrupted update	Restore the original target configuration or reconcile recovery records with the actual binding; do not simply delete them
TASK_CLOSED	The deployment record closed, its certificate version was replaced, or its node association became unavailable	Check the latest valid certificate, node association, and deployment record; start a new deployment if needed
TIMEOUT	An instance did not complete the deployment within the task deadline	Check the instance connection and local logs; reconnect and start a new deployment if needed

Deployment succeeded, but the service uses an old certificate

First identify what “succeeded” means:

• Certificate downloaded only confirms the download.
• Target synchronized means the target synchronization cycle completed without error. It may have deployed successfully or skipped an unnecessary update.
• For a file target without verify, a successful command exit does not prove the public endpoint's certificate changed.

Then check:

1. Does the application read the configured output files, rather than files in another directory?
2. Did the correct reload command run under the correct user, container, or service instance?
3. Is the browser reaching another server, load balancer, or CDN?
4. Does the hostname select a different HTTPS/SNI binding?
5. Has the platform's new version been downloaded while the local deployed version remains old and awaits a retry?

Offline instances

Use certone status and the local service or container logs to inspect an installation. The status command reads a saved snapshot: check its timestamp and recent connection logs before treating it as live status. A disconnected Agent's certificate files do not immediately become invalid.

Check whether the service or container is running, the network is reachable, and credentials are valid. Recreating an instance without retaining its state directory generates a new identity. Keep independent state directories for independent installations.

Deployment tasks do not wait indefinitely when no instance is online. The current waiting limit is 24 hours. After reconnecting, an instance checks the version it should deploy now, rather than replaying every completed historical task. A failed historical task does not necessarily mean the current certificate remains undeployed; inspect the latest instance status.

Recover after an interrupted deployment

For file targets, CertOne restores interrupted file writes before connecting to the platform, including during a network outage. If recovery reports RECOVERY_REQUIRED or ROLLBACK_RELOAD_FAILED, preserve the state directory and backups. Stop the agent, correct the rollback command (or reload when no rollback command is configured) for the same target name in config.yaml, then restart it. Recovery uses the corrected command with the restored files. Do not remove or rename that target until recovery completes, or delete the recovery journal to bypass an error. Container environment changes require recreating the container with the same data volume. During exec startup, files are recovered before starting the application; service reload is deferred until it is running.

A permanently rejected result report is logged as REPORT_REJECTED and retained in local result history. It appears in status under recent task history and does not block current certificate synchronization. Check the referenced task and local logs; do not delete all state to clear an old receipt. Temporary network or server errors keep the report queued for retry.

Export diagnostics and contact support

Export a diagnostic file as the actual runtime account:

certone diagnose --output certone-diagnostics.json

Add --config for a custom configuration path. If an administrator runs the process, the corresponding permissions are needed to read its configuration and state. Exporting diagnostics does not itself require administrator privileges.

The diagnostic file includes OS, architecture, program version, instance ID, state update time, certificate versions and hashes, deployment status, the number of pending result reports, and recent task result codes/stages. It also includes configuration, state and log locations to help identify the runtime setup. It excludes full configuration, private keys, Tokens, and command output. Paths and certificate or instance identifiers may still be internal information; inspect the file before sharing.

The diagnostic command requires readable, valid configuration; it also works before the first deployment and records that no state exists yet. Choose a new output filename for each report, because existing files are never overwritten. It does not create an archive of all logs. For initialization failures, provide version output and the error directly.

When contacting support, include:

• CertOne version, OS, and architecture.
• Runtime mode: local service, Docker, Synology, or IIS.
• Failure time and time zone, target name, error code, and relevant surrounding logs.
• Intended deployment destination and actual behavior.
• Troubleshooting steps already tried and the reviewed diagnostic file.

Logs limit command output length and attempt to redact secrets, but custom scripts must still avoid printing passwords or private keys. Do not submit Tokens, DSM passwords, PFX/JKS passwords, private key files, or an unreviewed complete state directory.