Troubleshooting: osTicket

Each issue is set out as the symptom you see, its cause, and the fix. For the setup steps themselves, see Connecting osTicket.

Plugin issues

Blank page after adding the plugin

Symptom: The osTicket Admin Panel shows a blank white page, or a PHP fatal error, after the plugin is added.

Cause: PHP is older than 8.1, or a required PHP extension is missing.

Fix:

Check the PHP version with php -v. The plugin needs 8.1 or higher.
Check that the json, curl and openssl extensions are loaded: php -m | grep -E 'json|curl|openssl'.
After upgrading PHP or enabling an extension, restart the web server: systemctl restart apache2 for Apache, or systemctl restart php-fpm for Nginx with PHP-FPM.

Flexivity AI is not listed under Add New Plugin

Symptom: Flexivity AI does not appear when you click Add New Plugin.

Cause: The file is not in osTicket’s plugin directory, or the web server cannot read it.

Fix:

Confirm the file is at include/plugins/fai-plugin.phar under your osTicket root.
Check that the web server user can read it:


ls -la /path/to/osticket/include/plugins/fai-plugin.phar

If not, set the owner and permissions as in Copy it into osTicket, and make sure the directory itself is readable:


chmod 755 /path/to/osticket/include/plugins/

“Permission denied” in osTicket’s system logs

Symptom: osTicket’s system logs (Admin Panel > Dashboard > System Logs) show “Permission denied” errors naming the plugin.

Cause: The .phar file or the include/plugins/ directory has the wrong owner or permissions.

Fix: Set them again as in the previous issue.

The plugin does not answer

Symptom: Plugin Info on the instance’s Help Desk page stays empty. Checking the plugin from the osTicket server returns 404:


curl -s -o /dev/null -w "%{http_code}\n" https://your-osticket/api/fai-plugin/v1/plugin-info

Cause: The plugin is not installed or not active, or the file is damaged.

Fix:

Check the plugin’s Status is Active under Admin Panel > Manage > Plugins.
If it is, download the plugin again from Edit Setup and replace the file.
A 401 from the same check is not a fault: the plugin is answering, and refuses the request only because Flexivity did not sign it. If Plugin Info is still empty, the problem is between Flexivity and osTicket. See Test Connection fails for a direct connection, or On-premise agent issues.

The wrong plugin version is shown

Symptom: After an upgrade, Plugin Info still shows the old version.

Cause: PHP’s opcode cache (OPcache) is still serving the old file, or the new file went somewhere else.

Fix:

Check the file’s modification time with ls -la /path/to/osticket/include/plugins/fai-plugin.phar.
Restart PHP to clear the cache: systemctl restart php-fpm, or systemctl restart apache2 for Apache with mod_php.

Plugin Info refreshes within a few minutes.

Test Connection fails

Test Connection is part of the direct connection. It shows why it failed:

Message	Cause	Fix
Plugin returned HTTP 404	osTicket is not routing to the plugin.	See The plugin does not answer.
Plugin returned HTTP 401	The plugin refused Flexivity’s signature: its Verification Key or Instance ID does not match this instance.	Copy both again from Edit Setup into the plugin’s settings, and save. A key rotated since is the usual cause.
A timeout, or the host cannot be reached	Flexivity cannot reach your osTicket over the internet.	Check the osTicket Host URL in Edit Setup, including `https://`. Check that your firewall allows inbound HTTPS from the internet. If osTicket cannot be reachable from the internet, use the on-premise agent instead.

On-premise agent issues

The agent runs as the agent service, in a container named fai-agent. Run the docker compose commands below in the directory holding its Compose file.

The agent cannot reach Flexivity

Symptom: The agent’s logs show repeated “connection failed” or “connection refused” errors, and the instance shows Disconnected.

Cause: Outbound connections are blocked, usually by a firewall or a proxy.

Fix:

From the agent’s server, check that Flexivity can be reached:


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

If it cannot, allow outbound access on port 443 to the Flexivity AI cloud, for both HTTPS and WSS.
If your network uses a proxy, add it to the agent service’s environment in the Compose file:


HTTPS_PROXY: 'http://proxy.example.com:8080'

Apply the change with docker compose up -d.

Authentication failed

Symptom: The agent connects, is refused with an authentication error, and disconnects.

Cause: The agent’s token, which is inside its Compose file, is invalid or has expired.

Fix:

Click Edit Setup on the instance’s Help Desk page, and go to Connect Agent.
Click Download docker-compose.yml. Each download carries a new token.
Replace the Compose file on the agent’s server with the new one, keeping any changes you made, such as a proxy.
Run docker compose up -d.

The agent reconnects about every two hours

Symptom: The agent works for roughly two hours, disconnects, and reconnects.

Cause: This is expected. The cloud closes each connection after two hours, so the agent reconnects by itself just before that.

Fix: None needed. If it disconnects much more often, look for network instability or a proxy with a short timeout.

The agent cannot reach osTicket

Symptom: The agent is connected, but Plugin Info stays empty. Its logs show “connection refused” or “name resolution failed” when it calls the plugin.

Cause: The agent calls osTicket at the osTicket Host URL set on the instance, from inside its container. There, localhost and 127.0.0.1 mean the container itself, not the server.

Fix:

Test from inside the container:


docker exec fai-agent curl -s -o /dev/null -w "%{http_code}\n" https://your-osticket/api/fai-plugin/v1/plugin-info

A 401 means the agent can reach the plugin.

If osTicket runs on the same server as the agent, add this to the agent service in the Compose file, run docker compose up -d, and set the osTicket Host URL in Edit Setup to http://host.docker.internal, with a port if osTicket needs one:


extra_hosts:
  - 'host.docker.internal:host-gateway'

If osTicket runs on another machine, use a hostname or IP address the container can reach.

Finding where the agent fails

If you are not sure where the problem is, work through these in order:

Is the agent running? docker compose ps should show fai-agent as Up. If it keeps restarting, its logs say why.
What do its logs say? docker compose logs agent --tail=50. Look for connection errors, authentication failures or crashes.
Can the server reach Flexivity? curl -I https://api.flexivity.ai/health. If not, outbound access is blocked; see The agent cannot reach Flexivity.
Can the agent reach osTicket? See The agent cannot reach osTicket. If osTicket answers from the server but not from the container, the cause is Docker networking.
Is its token good? If in doubt, download a new Compose file; see Authentication failed.

Ticket history issues

A sync stays at 0%

Symptom: A sync has started, but its progress does not move.

Cause: The connection is down, or the sync failed on its first batch.

Fix:

Check the instance is Active, with a recent heartbeat.
Cancel the sync and start it again. Tickets already indexed are skipped.

A sync takes hours

Symptom: A sync is progressing, but its estimated finish is hours away.

Cause: Each ticket is scrubbed of personal information and indexed, and a large archive takes a while: roughly 1–2 hours for 10,000 tickets, 4–8 hours for 50,000, and 12 hours or more beyond 100,000.

Fix: None needed. The sync runs in the background and does not slow osTicket down. If it is Interrupted, Resume it from Past Sync Jobs.

Getting help

If your issue is not covered here, contact Flexivity AI support through the admin console’s Help section, or email your account representative. Include:

the agent’s logs, if you run one: docker compose logs agent --tail=200
osTicket’s system logs: Admin Panel > Dashboard > System Logs
the plugin and osTicket versions, from Plugin Info
what you expected, what happened, and when