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. |
New in this release
These are refusals Alces raises itself, before (or instead of) sending anything to Jira. They're new in v1.1 — see Upgrading from 1.0.2 if you're seeing one of these for the first time after an upgrade.
| What you see | What it means | What to do |
|---|---|---|
"Transition \<id> (\<name>) on \<KEY> requires field(s) you did not supply: \<fields, with their allowed values>. Supply them in fields — Jira would otherwise accept the transition and leave the issue half-finished. ..." |
transition_issue checked the transition's screen first and found a required field that you didn't supply in fields and that the issue doesn't already have a value for. The call never reached Jira. (A required field the issue already carries doesn't trigger this — Jira keeps the existing value.) |
Supply the named field(s) in fields (the message lists each one's allowed values), or pass skipFieldValidation:true to send the request anyway and let Jira decide. |
| "Transition \<id> is not available on \<KEY>. Available transitions: \<list>." | The transition ID you asked for isn't one this issue currently offers — workflows and transition IDs vary by project and current status. | Call get_transitions on the issue to see what's actually available right now, and use one of those IDs instead. |
"Cannot update \<KEY>: \<field\> is not on \<KEY>'s Edit screen. ..." |
update_issue checked the issue's Edit screen first and found a field you're setting isn't on it. The call never reached Jira. |
Two remedies, depending on the field: for resolution, use transition_issue's fields argument on a resolving transition instead (see get_transitions with includeFields:true); for anything else, ask a Jira administrator to add the field to the issue's Edit screen — get_issue_edit_meta lists what's currently settable. Or pass skipFieldValidation:true to bypass the check and send the request anyway. |
| "Cannot update \<KEY>: Jira reports no editable fields on this issue — the acting account likely lacks the Edit Issues permission, or the issue is in a status its workflow marks non-editable (closed issues usually are). Pass skipFieldValidation:true to bypass this check." | update_issue asked Jira which fields are editable and Jira answered with an empty list. That's a permission or workflow-status problem, not a screen-configuration one — no field you could name would be settable. |
Check that your account has the Edit Issues permission on the project, and that the issue isn't closed (a closed issue's workflow status usually makes the whole issue read-only — reopen it first). Or pass skipFieldValidation:true to bypass the check, send the request and read Jira's own error. |
| "Request type \<id> on service desk \<id> requires field(s) you did not supply: \<fields, with their allowed values>. Add them to additionalFields (keyed by fieldId). ..." | jsm_create_request checked the request type's fields first and found a required one missing. The call never reached Jira. |
Add the named field(s) to additionalFields, keyed by field ID, or pass skipFieldValidation:true to send the request as-is. |
| "Could not read \<what> to pre-check \<what the check was for>: \<reason> Pass skipFieldValidation:true to bypass this check." | The pre-flight lookup itself failed (e.g. Jira returned a 403/404 on the metadata call) — this is different from the actual write failing. The underlying reason is included in the message, and the "to pre-check …" clause names what the tool was checking (required fields for transition_issue/jsm_create_request, which fields are settable for update_issue). |
Read the underlying reason the same way you would any other Jira error. If the lookup keeps failing but you're confident the fields you're sending are correct, pass skipFieldValidation:true to skip the check and call Jira directly. |
| "\<tool> requires confirm:true — this permanently deletes data. Confirm explicitly with the user before calling again with confirm:true." | You asked for a destructive action (delete, remove) without confirming first. | Confirm with the user, then call again with confirm: true. |
| "\<tool> requires confirm:true — this widens access: \<what specifically gets granted, e.g. "the user gains every permission the group grants">. Confirm explicitly with the user before calling again with confirm:true." | You asked for an action that grants a seat, membership, share, or role — not a deletion, but access-widening tools are gated the same way. The message names exactly what's being granted. | Confirm with the user, then call again with confirm: true. |
| "useAdminToken must be a boolean (got \<value>)." | You (or the agent) passed something other than a literal true/false for useAdminToken — e.g. a string or a number. |
Use a literal boolean. This only applies to tools that support token escalation in the first place — see the token escalation note on the README. |
| "useAdminToken:true requires the '\<domain>' domain to be listed in ALCES_TOKEN_ESCALATION_DOMAINS on this server — it isn't. ..." | You asked to escalate a call, but whoever runs this deployment hasn't opted that tool's domain into ALCES_TOKEN_ESCALATION_DOMAINS. |
Ask whoever runs your deployment to add the domain, or drop useAdminToken and proceed on your own permissions. |
| "useAdminToken is not available on \<tool>: it is a basic issue interaction, and Jira records who performed it — on the admin credential your work would be filed under the admin account, corrupting Jira's own record of who did what. Omit useAdminToken; this tool always runs on your own JIRA_USER_TOKEN." | You passed useAdminToken to a tool that creates, edits, transitions, assigns, comments on, votes on or watches a work item. Those can never use the admin credential — no deployment setting changes that. |
Drop the argument. If the call then fails on permissions, that's a real permission you need granted on your own account; the admin credential was never an option here. |
| "useAdminToken is not available on \<tool>: it is a self-scoped personal action — it acts on whoever is authenticated and names no target, so \"as someone else\" has no meaning here; on the admin credential it would read or write the admin account's own settings instead of yours. Omit useAdminToken; this tool always runs on your own JIRA_USER_TOKEN." | You passed useAdminToken to a tool about your account — your profile, permissions, preferences, favourites, share scope or session. Escalated it would answer about the admin account, not you. |
Drop the argument. If you meant to act on a different user, use the tool that names a target user instead (see docs/user/users-groups-permissions.md). |
| "useAdminToken is not available on \<tool>: it already runs on JIRA_ADMIN_TOKEN, so there is nothing to escalate to. Omit useAdminToken." | You passed useAdminToken to an admin-gated tool. Those already use the elevated credential for every call. |
Drop the argument — you already have what it asks for. |
| "useAdminToken is not available on \<tool>: it is a meta-tool answered by this server itself and never calls Jira, so no credential is ever selected for it. Omit useAdminToken." | You passed useAdminToken to get_api_references, list_tool_domains, activate_tool_domain or deactivate_tool_domain. These are answered by Alces itself and make no Jira request. |
Drop the argument. |
If a server log (not something you'd see as the end user, but worth knowing about if you run your
own deployment) shows [Alces] Warning: ALCES_TOOL_GROUPS contains unknown domain(s): ... or the
same for ALCES_TOKEN_ESCALATION_DOMAINS, a domain name in that environment variable was
misspelled — Alces drops the unrecognized name rather than silently never matching anything, and
the warning itself lists the valid domain names. Fix the spelling and restart the server.
Tool-specific gotchas
| Symptom | Cause | Fix |
|---|---|---|
A tool — admin-tier (admin_*, or anything on the Admin or Users, Groups & Permissions pages) or otherwise — never gets used, isn't in the tool list, or the agent says it doesn't have a way to do that. |
Two independent reasons a tool can be invisible: (1) it's admin-tier and JIRA_ADMIN_TOKEN isn't configured — admin tools are only registered with the agent when the server has that token; (2) its tool domain hasn't been activated for this session (Alces only advertises Core Issues & Search by default — see the tool visibility note on the README). Either way the tool isn't blocked, just not advertised — the agent has no way to know it exists. If a tool you used successfully before an Alces upgrade now behaves this way, or fails outright with "No Jira admin client configured — set JIRA_ADMIN_TOKEN to enable admin tools.", this release may have reclassified it as admin-tier — see Upgrading from 1.0.2. |
Ask whoever runs your Alces deployment whether JIRA_ADMIN_TOKEN is configured, or ask the agent to activate the tool's domain (activate_tool_domain, or "turn on the admin/agile/JSM/etc. tools"). If a tool was reclassified this release, that's expected behavior, not a bug — configure JIRA_ADMIN_TOKEN if you need it back. |
| A destructive action (delete, archive, trigger a reindex, cancel a cluster upgrade, etc.) — or an access-widening one (grant a seat, add someone to a group, share a filter, assign a role) — doesn't run even after you asked for it. | Many destructive or access-widening tools require an explicit confirm: true argument. The refusal names exactly what's being deleted or widened. A well-behaved agent will ask you to confirm before calling one of these rather than doing it silently. |
Explicitly confirm when asked ("yes, go ahead"). If the agent runs one of these 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. |
| Alces starts fine but every Jira tool call fails with "Could not reach Jira", and your client's log shows a "Could not reach Jira at startup" warning. | The server came up and connected to your client normally, but it couldn't reach Jira when it checked at startup — almost always VPN, JIRA_URL, or a firewall between the server and Jira. Alces deliberately starts anyway rather than refusing to launch, so you get a readable error from each tool instead of a server your client reports as broken. |
Fix the connectivity (connect the VPN, check JIRA_URL), then retry — no restart is needed for the network itself, though a changed JIRA_URL does need one (see the row below). |
You (or whoever runs your Alces deployment) just added/rotated JIRA_ADMIN_TOKEN, or changed ALCES_TOOL_GROUPS, and tools you expect still don't show up — even though activate_tool_domain/list_tool_domains report success. |
Credentials and ALCES_TOOL_GROUPS are both read once, when the server process starts. A running server doesn't re-read its environment, so a change made without restarting has no effect yet — and nothing in any tool's response tells you a restart is what's needed. |
Restart the Alces server process (or, for Claude Desktop/.mcpb, reload/reconnect the extension) after changing either of these, before assuming something's broken. |
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.