Troubleshooting

Connector Shows "Offline"

Symptoms: The connector was previously online but now shows as offline in the dashboard.

Possible causes:

1. Network connectivity — The connector cannot reach api.clariti-ai.xyz on port 443.

   # Test from the connector host:
   curl -sI https://api.clariti-ai.xyz/health
   

   If this fails, check your firewall rules and DNS resolution.

2. Container stopped — The Docker container may have exited.

   docker ps -a | grep clariti-connector
   docker logs clariti-connector --tail 50
   

3. Resource exhaustion — The container hit its memory or CPU limit.

   docker stats clariti-connector --no-stream
   

4. Transient network blip — The connector uses hysteresis: it must miss 3 consecutive polls (90 seconds) before being marked offline. A single missed poll does not trigger an offline alert.

Registration Fails

Symptoms: Entering the registration token returns "Registration failed."

Possible causes:

1. Token expired — Registration tokens expire after 24 hours. Go to the connector detail page in Clariti and click Regenerate Token.

2. Token already used — Each token can only be used once. If you need to re-register, regenerate the token.

3. Network issue — The bootstrap UI at port 8443 needs to reach api.clariti-ai.xyz. Check connectivity from the container:

   docker exec clariti-connector curl -sI https://api.clariti-ai.xyz/health
   

4. Rate limiting — After 5 failed attempts in 15 minutes, the connector rate-limits registration requests. Wait 15 minutes or restart the container.

Adapter Errors

Symptoms: An adapter configured on the connector shows errors or returns no data.

Possible causes:

1. Credential issues — Verify the credentials are correct. Re-enter them in the adapter settings.

2. Network access — The connector needs network access to the on-premises tool. Test from the container:

   # For an HTTPS API:
   docker exec clariti-connector curl -s https://your-tool:443/api/health
   
   # For LDAP/AD:
   docker exec clariti-connector python -c "import socket; socket.create_connection(('your-dc', 636), timeout=5); print('OK')"
   

3. TLS/certificate issues — If the on-premises tool uses a self-signed certificate, you may need to add the CA cert to the connector's trust store.

Viewing Logs

Container Logs

# Last 100 lines
docker logs clariti-connector --tail 100

# Follow live
docker logs clariti-connector -f

# Since a specific time
docker logs clariti-connector --since 2h

Connector Status

docker exec clariti-connector clariti-connector status

This shows:

• Registration state (registered / pending)
• Last successful poll time
• Buffer queue depth
• Connection health

Log Levels

Set CLARITI_LOG_LEVEL=debug for verbose output during troubleshooting:

docker run -e CLARITI_LOG_LEVEL=debug ... ghcr.io/clariti-ai/connector:latest

Re-registering a Connector

If you need to start fresh:

1. In the Clariti dashboard, go to the connector's Settings tab
2. Click Regenerate Token
3. On the connector host:

   docker exec clariti-connector clariti-connector reset
   docker exec clariti-connector clariti-connector enable-setup
   

4. Open https://<connector-ip>:8443 and enter the new token

Decommissioning a Connector

To permanently remove a connector:

1. In the Clariti dashboard, go to the connector's Settings tab
2. Click Decommission in the Danger Zone
3. Type the connector name to confirm
4. On the connector host, stop and remove the container:

   docker compose down -v  # -v removes the data volume
   

After decommissioning, the connector's credentials are invalidated and it can never re-authenticate.

Circuit Breaker

If the connector fails to reach Clariti for 10 consecutive polls, it enters degraded mode:

• Poll interval increases to 5 minutes (from 30 seconds)
• The health payload includes degraded: true
• The connector continues buffering adapter results locally
• When connectivity is restored, the connector exits degraded mode and uploads all buffered data

Disk Full

If the connector's data volume fills up:

• New adapter results are rejected (logged as warnings)
• Low-priority logs (debug, info) are evicted first to make room
• Error and warning logs are preserved as long as possible
• The health payload includes disk usage metrics

To resolve: expand the Docker volume or clear old data.