Skip to Content
IntegrationsosTicketTroubleshooting

Troubleshooting

This guide covers common issues encountered during setup and operation of the Flexivity AI osTicket integration. Each issue follows a Symptom, Cause, Fix format.

Note: For agent connection issues (firewall/network problems, authentication failures, WebSocket disconnects, Docker networking), see the Administration Guide — Troubleshooting page.

Plugin Issues

Plugin Not Detected

Symptom: The connection is established, but the administration console’s Plugin Info section is empty. The connection test fails on the “plugin unreachable” step.

Cause: The plugin is not installed, not activated, or Flexivity AI cannot reach the plugin’s REST API.

Fix:

  1. Verify the plugin is active in osTicket: Admin Panel > Manage > Plugins. Status should be Active.
  2. Test the plugin API directly from the osTicket server:
curl -s http://localhost/api/fai/plugin-info
  1. If this returns a 404, the .phar file may be missing or corrupt. Re-download and reinstall per the Plugin Installation guide.
  2. If this works from the server but not from the agent container, the issue is network connectivity — see the Administration Guide — Troubleshooting for Docker networking guidance.

Plugin Shows PHP Errors

Symptom: osTicket system logs contain PHP errors referencing the Flexivity AI plugin. The osTicket admin panel may show warnings.

Cause: PHP version incompatibility or missing extensions.

Fix:

  1. Check the PHP version: php -v. The plugin requires PHP 8.1+.
  2. Verify required extensions are loaded: php -m | grep -E 'json|curl|openssl'.
  3. If you recently upgraded PHP, restart the web server (Apache: systemctl restart apache2, Nginx + PHP-FPM: systemctl restart php-fpm).
  4. If the error is a specific class or function not found, the .phar may be from an incompatible version. Download the latest release and reinstall.

Plugin Version Mismatch

Symptom: The administration console shows a plugin version that does not match what you expect after an update.

Cause: The old .phar file is cached, or the new file was not copied to the correct location.

Fix:

  1. Verify the file on disk is the correct version:
ls -la /path/to/osticket/include/plugins/fai-plugin.phar

Check the file modification timestamp.

  1. Clear the PHP opcode cache if enabled (OPcache):
# Restart PHP-FPM to clear the cache
systemctl restart php-fpm
# Or for Apache with mod_php
systemctl restart apache2
  1. Verify the version by hitting the plugin API: curl -s http://localhost/api/fai/plugin-info.

AI Feature Issues

AI Summaries Not Generating

Symptom: Tickets are created or updated, but no AI summary appears.

Cause: Multiple possible causes, checked in order of likelihood.

Fix:

  1. Check feature is enabled: In the administration console, go to your instance’s Features section and confirm Ticket Summary is toggled on.
  2. Check connection is active: The instance status must show Connected with a recent heartbeat.
  3. Check for processing errors: On the instance Dashboard, check the failure count. If jobs are failing, review the job history for error details.
  4. Check the event queue: Events are first written to the fai_event_queue table in osTicket’s database. If events are not appearing there, the plugin’s signal handlers may not be firing. Verify the plugin is Active.
  5. Check logs: Review the instance’s job history in the administration console 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 the historical sync has not been run.

Fix:

  1. Check whether Historical Sync has been completed. In the administration console, go to the Features section and check the Historical Sync status.
  2. If the sync has not been run, start one. 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.

Connection Test Failures

Test Connection Fails at “Agent Reachable” Step

Symptom: Clicking “Test Connection” in the administration console fails on the first check — the cloud cannot reach the agent.

Cause: The agent is not connected to the cloud, or has recently disconnected.

Fix:

  1. Verify the agent container is running: docker compose ps.
  2. Check agent logs for connection errors: docker compose logs fai-agent --tail=20.
  3. If the agent shows as connected in the logs but the test fails, try again after 10-15 seconds — the agent may be in the process of reconnecting.

Test Connection Fails at “Plugin Reachable” Step

Symptom: The connection is established (first check passes), but the test fails when trying to reach the osTicket plugin.

Cause: Flexivity AI cannot reach the osTicket URL configured during setup.

Fix:

  1. Verify the osTicket URL configured in the instance setup is correct.
  2. For agent mode, test from inside the agent container:
docker exec fai-agent curl -s http://your-osticket-url/api/fai/plugin-info
  1. If this fails, see the Administration Guide — Troubleshooting for Docker networking guidance.

Historical Sync Issues

Sync Stuck at 0% or Not Progressing

Symptom: A historical sync job was started but the progress stays at 0% or does not advance.

Cause: The connection may be down, or the sync job encountered an error on the first batch.

Fix:

  1. Confirm the instance is connected and healthy (green status, recent heartbeat).
  2. Check the sync job details in the administration console for any error messages.
  3. If the job is stuck, cancel it and start a new sync. The new job will resume from the last successfully processed ticket.

Sync Takes Very Long

Symptom: The historical sync is progressing but the estimated completion time is many hours.

Cause: Large ticket archives with many messages per ticket take longer to process. Each ticket’s content must be embedded, which involves PII scrubbing, sending data to the cloud, and generating vector embeddings.

Fix:

This is generally expected for large archives. Some guidance:

  • 10,000 tickets: Expect 1-2 hours.
  • 50,000 tickets: Expect 4-8 hours.
  • 100,000+ tickets: May take 12+ hours.

The sync runs in the background and does not impact osTicket performance. Let it complete. If it fails partway through, restarting it will pick up where it left off.

Getting Additional Help

If the issue is not covered here:

  1. Collect the following information:

    • Instance logs from the administration console’s job history
    • osTicket system logs: Admin Panel > Dashboard > System Logs
    • Plugin version and osTicket version (from the administration console’s Plugin Info section)
    • A description of what you expected vs. what happened

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

Last updated on
Integration ApproachSecurity