This documentation always describes the latest published version.
The server writes to stderr and to the file ~/.claude/mcp-servers/osticket/logs/server.log. With LOG_LEVEL=debug in the .env you get more messages.
tail -f ~/.claude/mcp-servers/osticket/logs/server.log
The file contains start and stop messages and warnings about the health check and retries. The cause of many tool errors is not in there, see the section on Unexpected error.
| Symptom | Cause and solution |
|---|---|
The client shows no osticket_* tools |
Server not registered, dist/index.js missing, or the client was not restarted. Build with npm run build and check the registration |
Missing required environment variable |
OSTICKET_API_URL or OSTICKET_API_KEY is not set. Check ~/.claude/mcp-servers/osticket/.env |
OSTICKET_API_URL must use HTTPS |
The URL starts with http://. Use https:// or set ALLOW_HTTP=true for local tests |
Invalid OSTICKET_API_URL |
The URL is not a valid URL, for example because the scheme is missing |
Invalid OSTICKET_DEFAULT_TOPIC_ID or Invalid OSTICKET_DEFAULT_EMAIL |
The value has the wrong format |
The .env is not found |
It is only looked up at ~/.claude/mcp-servers/osticket/.env and in the working directory. Otherwise pass the variables through env in the client |
Warning Health check failed in the log |
The request to /api/tickets-stats.php failed. Check URL, key, the plugin API Endpoints and the permission can_read_stats or can_read_tickets |
| Message | Meaning and solution |
|---|---|
Authentication failed. Check OSTICKET_API_KEY ... (401) |
The key is missing, unknown or inactive, or the IP does not match. The plugin API Endpoints also answers with 401 when the key only lacks the permission for that endpoint. The server hides the exact text, so check key, IP and permission in osTicket |
Permission denied ... (403) |
For subtickets, can_manage_subtickets is missing or the key's department restriction excludes the ticket. For attachment download there is no attachment entry for this file_id |
Resource not found ... (404) |
The ticket or file does not exist. When creating, it can also mean the endpoint /api/wildcard/tickets.json is missing because the plugin API Key Wildcard is not active |
Feature not available ... (501) |
The plugin Subticket Manager is not installed or not active |
osTicket API error: ... (422) |
The link already exists or the child already has a different parent. The text from osTicket is part of the message |
osTicket API error: ... (400) |
The plugin rejects the input, for example an invalid value or a parent ticket that is itself a child. The text from osTicket is part of the message |
Request timed out |
osTicket does not answer within 10 seconds, even after the retries |
Cannot connect to osTicket server |
The host refuses or drops the connection |
osTicket host not reachable |
The host name of the URL cannot be resolved |
TLS/SSL connection error |
Certificate or protocol is faulty. Fix the certificate. OSTICKET_API_REJECT_UNAUTHORIZED=false bypasses the check but is insecure |
Unexpected error occurred. Check server logs for details. This message replaces the exact cause, and the server does not write it to the log. Typical reasons are:
osticket_get_ticket with neither id nor number.In these cases, check your input.
The list ignores my department filter. The parameter departmentId of osticket_list_tickets currently has no effect: the server sends it as departmentId, while the plugin only reads department. The list comes back unfiltered. Filter the results yourself, for example by the department field in the response.
The list ignores my status filter. The plugin does not filter when the status name matches no status of the instance. Use the status names of your instance, usually open, closed, resolved and archived.
osticket_update_ticket reports success but changes nothing. A call with only number passes validation and sends nothing meaningful. Pass at least one field.
osticket_get_ticket with id returns the wrong ticket. The server sends the id as a ticket number, and the plugin looks for the number first. Use number whenever possible.
A ticket was created twice. If the response times out, the server repeats the request. Before creating again, check with osticket_search_tickets whether the ticket already exists.
A large attachment cannot be downloaded. osTicket's response, including Base64, may be at most 10 MB, so files up to roughly 7.5 MB.
The search does not find a ticket number. The plugin searches the subject. Fetch a ticket by its number with osticket_get_ticket.
total for list and search is too small. The tool does not return a total count. total of the search is the number of returned hits. Request further pages with offset while has_more is true (only osticket_list_tickets).
osTicket lives in a subdirectory. The server discards the path of the base URL and calls https://host/api/.... osTicket has to be reachable at the root of the host.