Quick reference for the most common issues. If nothing here helps, contact [email protected] — include your workspace ID (from Settings → Workspace) and a timestamp.

​
Agent won’t connect

Symptom: Integrations → Agent Setup shows the agent stuck in disconnected, or a newly-installed agent never appears in the inventory.
1

Check the agent logs on the host

journalctl -u tigertrust-agent -f          # systemd
docker logs tigertrust-agent               # container
Look for dial tcp:, EOF, certificate verify failed, or 401 Unauthorized.
2

Confirm outbound reachability

The agent talks to our Collector over HTTPS. From the host:
curl -v https://collector.tigertrust.io/healthz
Expected 200 OK. If TLS or DNS fails, your egress firewall or DNS resolver is blocking the connection.
3

Verify the enrollment token

Tokens are single-workspace, revocable at any time. If someone rotated it after install:
  • Integrations → Agent Setup → Regenerate token
  • Reinstall (or edit /etc/tigertrust/agent/config.yaml) with the new token
  • systemctl restart tigertrust-agent
4

Check the audit log

Monitoring → Audit Logs, filter by action = agent.enroll.failed. The reason column tells you exactly why: expired token, wrong workspace, invalid signature.

​
Certificate issuance fails

  • Verify the target hostname resolves publicly (dig +short <host>).
  • Confirm port 80 is open from the internet to the responding agent — HTTP-01 requires plain HTTP briefly.
  • Check the ACME challenge log under Certificates → Issue → Recent Attempts. Timeout waiting for challenge = firewall; unauthorized = wrong file served.
  • Under Integrations → DNS Providers, click Test on the provider. It should return “credentials valid”.
  • Confirm the API credentials have write permission for the zone you’re issuing for.
  • For providers with slow propagation (some managed DNS): increase the propagation-wait under Advanced settings.
  • Authorities → CA Management → your CA → Health shows the last error. 401 = expired API credentials. 403 = domain not on your account’s whitelist.
  • Contact your CA’s account manager to confirm the domain is authorised on your contract.
Check the policy on the template you used (Certificates → Templates). Common causes:
  • Key size below policy minimum (bump the CSR key size)
  • Subject CN/SAN doesn’t match template regex
  • Requested validity exceeds template max

​
Discovery scan finds nothing

Symptom: cloud discovery scan completes successfully but no certificates appear.
1

Verify IAM permissions

Each cloud provider has a minimum required IAM policy — see AWS, Azure, GCP. Cross-check the policy attached to the credentials you added.
2

Check regions

Scans default to the regions in your provider config. Certificates in other regions won’t be discovered until you add them.
3

Look for filter mismatches

Discovery → Discovered Certificates hides items that already match a live cert. Toggle Show already-imported to see everything.

​
Webhooks not firing

1

Check delivery attempts

Integrations → Webhooks → your endpoint → Deliveries. Each attempt shows the response code and body from your server.
2

Common failure codes

  • 401/403: your server rejected our request. Verify your signature-verification logic. See Webhooks.
  • 5xx: your server errored. Fix the endpoint; we retry with exponential backoff.
  • timeout: your endpoint took >10 seconds. Move heavy work to a background queue and 200 immediately.
3

Endpoint auto-disabled?

After 10 consecutive failures we disable an endpoint to protect your infrastructure. Fix the issue, then hit Re-enable on the endpoint page.

​
SSO login fails

IdP metadata drifted. Settings → SSO → your provider → Refresh metadata.
The user’s email domain isn’t mapped to a workspace. Add a mapping under Settings → SSO → Domain mappings, or invite the user manually first.
The IdP isn’t sending the group claim we expect. Check the Group attribute setting under Settings → SSO → your provider. Common defaults: groups, memberOf, roles.

​
TPM attestation denied

Symptom: the attest-and-provision call returns 403 attestation_failed. The response failures[] array tells you exactly which check tripped. Common codes:
FailureMeaningFix
quote_verify: nonce mismatchAgent used a stale or wrong nonceAgent should fetch a fresh nonce per attestation
pcr_mismatch:<n>PCR value differs from policy expectationDevice boot state changed. Verify with tpm2_pcrread and update the policy if legitimate
pcr_missing:<n>Policy requires this PCR but agent didn’t quote itAdd the PCR to the agent’s pcr_selection config
certify_verify: bound public key modulus does not matchCSR key doesn’t match TPM2_CertifyAgent bug — regenerate CSR from the same TPM-resident key
ek_chain: ...EK certificate doesn’t chain to a trusted rootContact support to add your TPM vendor’s root to our trust store
nonce_expiredAgent took >5 minutes between challenge and evidenceReduce agent-side latency; the default TTL is 300 seconds
secure_boot_not_measuredPCR7 is zero — Secure Boot is offEnable Secure Boot in device firmware, then re-attest
See TPM policies for how to relax or tighten policy safely.

​
Collecting a support bundle

When escalating, include:
  1. Your workspace ID (Settings → Workspace → General).
  2. Timestamps in UTC with a ±5-minute window.
  3. The relevant audit-log entries (Monitoring → Audit Logs → Export CSV).
  4. For agent issues: last 500 lines of agent logs (journalctl -u tigertrust-agent -n 500 > agent.log).
  5. For webhook issues: the delivery attempt IDs from the Deliveries tab.
Email the bundle to [email protected] with a description of what you expected vs. what happened.

​
Next steps

Audit logs

Correlate an incident against every recorded action.

Alerts

Set thresholds so we catch the next occurrence for you.

Notifications

Route alerts to Slack, PagerDuty, or your webhook of choice.

Agents and Collector

Deeper dive on agent connectivity and enrollment.