Troubleshooting Installation

Most installation issues fall into three buckets: connectivity, certificates, and resource limits. Work through the checks below in order.

Agent not appearing in the console#

Check the agent status and logs on the host:

applicare-agent status
journalctl -u applicare-agent -n 100 --no-pager

• Connection refused / timeout: verify outbound 443 to the server and any proxy setting.
• 401 enrollment: the token expired — generate a fresh one under Settings → Agents.
• Clock skew: TLS fails if host time drifts > 5 min. Enable NTP.

Certificate errors#

If you use a private CA, add the CA bundle so the agent trusts the server:

applicare-agent config set tls.ca_file=/etc/pki/ca.pem
systemctl restart applicare-agent

For evaluation only, --insecure skips verification — never use it in production.

Server won't start#

Inspect the server log and health endpoint:

docker compose logs applicare-server   # compose
kubectl logs -n applicare deploy/applicare   # helm
curl -k https://localhost:8443/healthz

The most common causes are insufficient RAM (needs 16 GB+), a port already bound, or a full data volume. The health output names the failing subsystem.

Still stuck?#

Collect a diagnostics bundle with applicare-agent diag (or applicare-server diag) and open a ticket from the Support page.