Skip to Content
Administration GuideTroubleshooting

Troubleshooting

This guide covers common issues encountered when connecting and operating Flexivity AI with your helpdesk application. Each issue follows a Symptom, Cause, Fix format.

Agent Connection Issues

Agent Cannot Connect to Cloud

Symptom: The agent logs show repeated “connection failed” or “connection refused” errors. The admin console at app.flexivity.ai  shows the instance as Disconnected.

Cause: Outbound WebSocket connections to the cloud are being blocked, typically by a corporate firewall or proxy.

Fix:

  1. Verify the host can reach the cloud endpoint:
curl -I https://api.flexivity.ai/health

  1. If the request fails, check your firewall rules. The agent requires outbound access on port 443 (WSS over TLS) to the Flexivity AI cloud.

  2. If your network uses an HTTP proxy, configure it in the Docker Compose environment:

environment:
  - HTTPS_PROXY=http://proxy.example.com:8080
  1. Restart the agent after making changes: docker compose restart fai-agent.

Authentication Failed

Symptom: The agent connects but immediately receives an authentication error and disconnects.

Cause: The API token is invalid, expired, or has been revoked.

Fix:

  1. Log in to the admin console at app.flexivity.ai  and navigate to the instance’s Agent Credentials section.
  2. If the token has been revoked or you suspect it is invalid, generate a new token.
  3. Update the FAI_API_TOKEN value in your .env file.
  4. Restart the agent: docker compose restart fai-agent.

Agent Connects Then Disconnects After Approximately 2 Hours

Symptom: The agent works for approximately 2 hours, then disconnects and reconnects.

Cause: This is expected behavior. AWS API Gateway closes WebSocket connections after 2 hours. The agent is designed to detect this and automatically reconnect at the 110-minute mark.

Fix: No action needed. The agent handles reconnection automatically. If you see frequent disconnects much sooner than 2 hours, check for network instability or proxy timeout settings.

Docker Networking Issues

Symptom: The agent container starts but cannot reach your helpdesk application. Logs show “connection refused” or “name resolution failed” when trying to contact the plugin API.

Cause: The FAI_INSTANCE_URL is not reachable from inside the Docker container. This commonly happens when using localhost or 127.0.0.1, which refer to the container itself rather than the host.

Fix:

  1. If your helpdesk runs on the same host as the agent, use the Docker host gateway:
# In docker-compose.yml, add to the fai-agent service:
extra_hosts:
  - 'host.docker.internal:host-gateway'

Then set FAI_INSTANCE_URL=http://host.docker.internal (or the appropriate port).

  1. If your helpdesk runs on another machine, use its network hostname or IP address that is reachable from the Docker bridge network.

  2. Test connectivity from inside the container:

docker exec fai-agent curl -s http://your-application-url/api/fai/plugin-info

Connectivity Diagnostics

If you are unsure where the connection is failing, follow these steps to isolate the issue:

1. Verify the Agent Container Is Running

docker compose ps

Confirm the agent container shows a status of “Up”. If the container is restarting in a loop, check the logs for the root cause.

2. Check Agent Logs

docker compose logs fai-agent --tail=50

Look for connection errors, authentication failures, or crash messages.

3. Test Outbound Connectivity

From the host machine:

curl -I https://api.flexivity.ai/health

If this fails, outbound HTTPS/WSS is blocked at the network level.

4. Test Application Reachability from the Agent

docker exec fai-agent curl -s http://your-application-url/api/fai/plugin-info

If this fails but the application is reachable from the host, the issue is Docker networking (see Docker Networking Issues above).

5. Verify Token Validity

In the admin console at app.flexivity.ai , navigate to the instance detail page and check the Agent Credentials section. If in doubt, regenerate the token, update the .env file, and restart the agent.

AI Feature Issues

AI Features Not Producing Output

Symptom: Features are enabled but no summaries, recommendations, or other AI output is appearing.

Fix:

  1. Check the agent is connected: The instance status must show Active with a recent heartbeat in the admin console.
  2. Check features are enabled: Navigate to the instance detail page and confirm the desired features are toggled on.
  3. Check for processing errors: On the instance detail page, review the failure count for each feature. If jobs are failing, the job history may contain error details.
  4. Check agent logs: docker compose logs fai-agent --tail=50 for any errors processing events.

Recommendations Are Empty or Low Quality

Symptom: Ticket Recommendations return no results or suggest irrelevant tickets.

Cause: The knowledge base does not have enough historical ticket data, or Historical Sync has not been completed.

Fix:

  1. Check whether Historical Sync has been completed on the instance detail page in the admin console.
  2. If the sync has not been run, enable it. Recommendations improve significantly with a larger corpus of resolved tickets.
  3. If the sync completed but recommendations are still poor, the ticket volume may be too small for meaningful similarity matching. The system works best with at least several hundred resolved tickets.

Getting Additional Help

If the issue is not covered here:

  1. Collect the following information:

    • Agent logs: docker compose logs fai-agent --tail=200
    • Your helpdesk application’s system logs
    • Plugin version and application version (from the admin console’s Application Information section)
    • A description of what you expected vs. what happened

  2. Contact Flexivity AI support through the admin console’s Help section or email your account representative.

Last updated on
Account SettingsOverview