Troubleshooting

This guide walks you through diagnosing problems in Horizon, organised by area. It focuses on how to investigate — the diagnostic tools available, what to check, and how to interpret what you find.

For specific questions and known answers, see the FAQ. If a problem isn't covered here or in the FAQ, see Getting more help for what to collect before contacting support.

First steps

A few things make every problem faster to diagnose.

Read the error code. Horizon errors include a machine-readable code (for example HQL-001 for a malformed search query) and usually a precise line or location. The code is the fastest path to the cause — search this guide or the FAQ for the code directly.

Check the audit trail. Most lifecycle and configuration actions are recorded as events in the audit trail. If something "didn't happen", the events view will usually show whether the action was attempted, rejected, or never triggered. Filter by the relevant certificate, request, or time window.

Confirm what your account can do. Many "it doesn't work" reports are permission boundaries rather than faults. Your roles, teams, and permissions determine which profiles and actions are available. When in doubt, compare what you see against what an administrator account sees.

Reproduce with the simplest possible input. Before escalating, try to reproduce the issue with a single certificate, a minimal query, or a stripped-down request. This almost always reveals the variable that matters.

Determine whether it's a software defect. If the behaviour changed without any configuration change on your side — it worked yesterday and nothing was modified — note when it last worked correctly and what, if anything, changed around that time (a new certificate, a different client version, a network change). That context is the fastest way to confirm a defect and lets support act immediately. If you can reproduce the issue consistently, include the exact steps. See Getting more help for what to collect before contacting support.

Sign-in & access

Sign-in problems fall into three categories: credential issues, identity provider (IdP) issues, and permission issues once logged in.

Credential and IdP issues. Horizon supports both local credentials and external IdP (corporate SSO). The login screen selects between them. If login fails, confirm you are using the right provider. If you authenticate through a corporate IdP, verify with your internal IT that the IdP is reachable and your account is active.

Missing features or profiles. Visibility in Horizon follows permissions strictly. If a profile, action, or section isn't shown, your account likely lacks the permission or the object belongs to a team you are not a member of. Check your assigned roles and teams before assuming something is broken.

Ownership and teams. Certificate ownership can be direct (assigned to you) or indirect (through a team). Certificates that appear missing are often a team-membership issue rather than a missing certificate. Ask your administrator to verify your team assignments.

See the Sign-in & access FAQ for specific scenarios.

Searching the inventory

Horizon uses its own query languages — HCQL for certificates, HRQL for requests, and related variants for events and discovery. These are not SQL. Most search problems are syntax habits carried over from SQL or incorrect assumptions about field names.

Start with a broad query. If a search returns nothing or an error, remove all filters and add them back one at a time. This isolates which clause is the problem.

Check the error location. An HQL-001 error includes a line and column number pointing at the offending token. Go to that position first before changing anything else.

Field names are lowercase and context-specific. Field names differ between HCQL, HRQL, and the events query language. A field that works in one context may not exist in another.

Status filters are exclusive. status is valid excludes expired and revoked certificates. If you expect to see a certificate that isn't appearing, remove the status clause first.

Relative date units are limited. Supported units are days (d), hours (h), minutes (m), and seconds (s). There are no week or month shorthand values — use 30d, not 1month.

See the Searching the inventory FAQ for syntax examples and common mistakes.

Certificate lifecycle

Most certificate lifecycle problems are one of three things: a permission issue, an expected workflow state, or a profile policy constraint.

Trace the request. Every enrollment, renewal, or revocation creates a request record. Open it to see its current state, any error messages, and who acted on it. The audit trail attached to the request shows the full history.

Understand pending vs. direct. A request in "Pending" is not an error — it means the profile requires approval and none has been given yet. If you expect immediate completion but get a pending state (or vice versa), the permission configuration on the profile is the variable to check.

Profile constraints are intentional. If a subject field is greyed out, a SAN type is absent, or the enrollment mode doesn't match what you need, that is deliberate policy set on the profile. The request form shows exactly which fields are editable and which SAN types are allowed.

Enrollment protocol issues (EST, SCEP, ACME, MDM). For automated enrollment protocols, work through the chain: network reachability, correct endpoint URL, valid and current challenge or credential, and accurate device clock. A failed protocol enrollment almost always produces a clear error on the client side that points to which step failed.

Expiry and renewal. Renewal is not always possible on an expired certificate — profile policy may prevent it. If renewal is blocked, enroll a new certificate and revoke the old one. Set up expiry notifications to avoid reaching this situation.

See the Enrollment & issuance FAQ and Renewal, expiry & revocation FAQ for specific answers.

Discovery

Discovery problems are almost always scope or reachability issues. Horizon only knows about certificates that a discovery campaign has actually found.

Verify the campaign ran. Check that a discovery campaign exists for the relevant network ranges or sources and that it has completed a scan recently. A campaign that was never run, or ran before a host was added to scope, will not show that host's certificates.

Check reachability. The scanning component must be able to reach the target hosts. Firewall rules, network segmentation, or hosts that were offline during the scan window are common causes of missing certificates.

Spot-check a specific host. Horizon's certificate decode utilities let you verify what a host is currently presenting. Compare that against the inventory to confirm whether the certificate exists but wasn't discovered, or whether the host is presenting something unexpected.

Discovered certificates and licensing. Certificates in monitoring or discovery profiles are intentionally excluded from licensed usage counts. See the Discovery FAQ and Licencing FAQ for details.

Automation & notifications

Automation problems — REST triggers, email notifications, and scheduled actions — follow a consistent diagnostic path: confirm the trigger exists, is attached to a profile, is configured for the right event type, and that its target is reachable.

REST triggers (deployment triggers).

1. Confirm the trigger is attached to the relevant profile — an unattached trigger never fires.
2. Confirm the trigger's event type matches the lifecycle event you are watching (issuance, renewal, revocation, etc.).
3. Use the test-fire feature to send a real request to the target and inspect the response.
4. If the trigger fires but fails, check success codes, credentials, timeouts, and proxy configuration.

Email notifications. All email notifications go through the SwissSign Email Gateway. If emails are not arriving, confirm that the From address is set to no-reply@clm.swisssign.com and that your mail system is not blocking that sender.

Expiry vs. licence notifications. Certificate expiry notifications and licence expiry notifications are configured separately. Confirm you have configured the right event type for what you want to be alerted on.

See the Notifications FAQ for specific scenarios.

Network & WAF

Unexpected HTTP 403 in the UI or API. A 403 that appears without a clear permission reason may be caused by the WAF (Web Application Firewall) policy blocking a request whose content was flagged as abnormal — for example, a query or payload containing patterns that resemble an attack signature.

To confirm the WAF is the cause, inspect the response headers. A WAF-blocked request includes:

• waf-block: request
• x-request-id: <identifier>

If both headers are present, the request was blocked by the WAF rather than by Horizon. Share the x-request-id value with our support team — it allows them to look up the exact rule that triggered the block and determine whether an exception is needed.

Configuration & files

Product manual. For in-depth configuration reference — protocols, PKI connectors, profiles, and advanced settings — refer to the Horizon Admin Guide.

See the Configuration FAQ and Files & formats FAQ for specific answers.

Getting more help

If this guide doesn't resolve your issue, contact support or our Professional Services team with the following so they can diagnose quickly:

• Your tenant identifier and the approximate time the issue occurred.
• The exact error code and message (for example HQL-001), copied rather than paraphrased.
• The request ID for a failed lifecycle action, or the certificate identifier involved.
• What you expected to happen versus what happened.
• The steps to reproduce, if known.

For configuration or integration problems, you can also export your Horizon CLM cookbook and attach it to your request so support can review your setup. The cookbook contains no private keys, certificates, credentials, or user data, so it is safe to share.