Troubleshooting
Most problems you'll hit fall into a handful of patterns. This page lists what you'll actually see and what to do about it.
Errors from Jira
Alces turns Jira's raw HTTP errors into a plain-language message before the agent shows it to you. If you see one of these, here's what's really going on:
| What you see | What it means | What to do |
|---|---|---|
| "Jira rejected the request (401 Unauthorized) — check your JIRA_USER_TOKEN/JIRA_ADMIN_TOKEN." | The Personal Access Token (PAT) configured for the server is missing, expired, or revoked. | Ask whoever set up your Alces connection to check the PAT in Jira (Profile → Personal Access Tokens) and reconfigure it if needed. This isn't something you can fix from within a chat with the agent. |
| "Jira denied permission (403 Forbidden) for this operation under the acting token's permissions." | The request reached Jira fine, but the PAT's Jira user doesn't have permission for that action (e.g. no Edit permission on the project, no admin rights). | Check what Jira permissions the account behind the PAT actually has. If you expected this to work, it may need a different token — for admin-tier tools, that means JIRA_ADMIN_TOKEN specifically (see below). |
| "Jira could not find the requested resource (404 Not Found)." | The issue key, project key, ID, or other identifier doesn't exist, or the acting token can't see it (Jira often returns 404 instead of 403 for things you can't browse, to avoid leaking existence). | Double-check the key/ID. If you're sure it exists, this may actually be a permissions problem in disguise — see 403 above. |
| "Jira rejected the request (400 Bad Request): ..." | The request was malformed or failed Jira-side validation — the message after the colon is Jira's own validation detail (e.g. a required field missing, an invalid transition). | Read the detail message; it usually names the exact field or reason. Rephrase your request with the missing/corrected information. |
| "Jira rate-limited the request (429 Too Many Requests) — this is retryable; back off and try again." | Too many requests hit Jira too quickly. | Wait a moment and ask again. This is transient, not a configuration problem. |
| "Jira API error \<other status>: ..." | An error Alces doesn't have a specific friendly message for yet — the raw (truncated) response body is included. | Share the message with whoever administers your Alces deployment; it may need a new error mapping. |
| "Could not reach Jira at \<host> — check JIRA_URL, VPN, and TLS settings." | The request never got a response from Jira at all — a DNS lookup failure, a refused/reset connection, a timeout, or a TLS/certificate problem, usually meaning JIRA_URL is wrong, you're not on the right network/VPN, or the Jira host is down. |
Check that JIRA_URL is spelled correctly and actually resolves from where the server runs; confirm you're connected to your organization's VPN if Jira DC is internal-only; ask whoever runs your deployment to verify the host is reachable. |
| "This looks like Jira Cloud (\<host>) — Alces supports Jira Data Center only." | JIRA_URL points at a Jira Cloud instance (a *.atlassian.net address) instead of Data Center. |
Alces doesn't work with Jira Cloud at all — point JIRA_URL at your organization's Jira Data Center (or Server) instance instead. See Install to use in the main README. |
Tool-specific gotchas
| Symptom | Cause | Fix |
|---|---|---|
An admin tool (admin_*, or anything documented on the Admin or Users, Groups & Permissions pages) never gets used, or the agent says it doesn't have a way to do that. |
Admin-tier tools are only registered with the agent at all when the server has JIRA_ADMIN_TOKEN configured. If it isn't set, those tools are completely invisible — not blocked, not advertised — so the agent has no way to know they exist. |
Ask whoever runs your Alces deployment whether JIRA_ADMIN_TOKEN is configured. If it's intentionally not configured, this is expected behavior, not a bug. |
| A destructive action (delete, archive, trigger a reindex, cancel a cluster upgrade, etc.) doesn't run even after you asked for it. | Many destructive or high-impact tools require an explicit confirm: true argument. A well-behaved agent will ask you to confirm before calling them rather than doing it silently. |
Explicitly confirm when asked ("yes, go ahead"). If the agent runs a destructive action without asking you to confirm first, something's wrong — don't approve it, and flag it to whoever runs your deployment. |
| A JQL or AQL search returns zero results even though you're sure matching issues/objects exist. | Most commonly a typo'd field name, a value that doesn't match Jira's exact spelling (e.g. status names are case- and instance-specific), or you genuinely don't have permission to see the matching items. | Ask the agent to look up valid values first — list_statuses/list_priorities/get_jql_suggestions for Jira issues (see Core Issues & Search), or check your AQL syntax against the Assets AQL reference (see JSM Assets). |
| A search or list response says results were cut off / only shows a partial list. | List-returning tools cap how many results come back in one response, to keep replies a manageable size. The response tells you when this happened and roughly how many more exist. | Narrow your search (add more filter conditions) instead of trying to page through everything at once — a smaller, complete result set is more useful than a partial large one. |
jsm_add_comment shows up somewhere the customer wasn't supposed to see it. |
JSM comments are public (visible to the customer) by default. If you wanted an internal, agent-only note, you need to say so explicitly. | Ask for an "internal note" or "agent-only comment" specifically — see JSM Service Desk. |
| Agile tools (boards, sprints, epics — see Agile) don't work at all on this Jira instance. | Several agile tools require the Jira Software application to be enabled (and licensed) on the target instance — a JSM-only or core-Jira-only Data Center deployment won't have it. | Confirm with your Jira administrator whether Jira Software is installed and licensed on this instance. |
| A field you expect to see on an issue/project/object is missing from the agent's response. | Responses are trimmed to the fields that matter for the request, not Jira's full raw payload, to keep replies readable. | Ask for the specific field by name — the agent can widen the request. |
Still stuck?
For the full technical picture of what's implemented (every field, every parameter, every Jira REST endpoint behind each tool), see docs/api-catalog.md. If none of the above matches what you're seeing, the issue is most likely specific to your Jira instance's configuration or the Alces deployment itself — check with whoever set up your connection.