JIRA Connection Errors
Explanation
A JIRA Macro that cannot obtain its data displays an error in place of the issues rather than rendering nothing, so the reader knows the content is missing. Which error appears tells what went wrong, and the four cases below cover them all.
Two of them come from JIRA rejecting the request rather than from a broken connection, which is why they are worth distinguishing: the wiki reaches JIRA with the single account configured for the instance, and JIRA refuses a query as a whole when that account may not read one of the issues it selects. An error is therefore as often a rights question as a connectivity one.
JIRA Returned an Error of the Request
The page shows "JIRA returned an error of the request. This could be related to the JQL query or a rights limitation in JIRA for the XWiki user.", followed by the messages JIRA itself produced.
Cause
JIRA answered with an HTTP 400 or 401 status. It does so both for a query it cannot parse and for a query whose results the requesting account may not read, and it does not distinguish the two. Confidential issues caught by an otherwise valid query are the most frequent cause, because JIRA rejects the whole request instead of omitting them.
Solution
Read the messages JIRA appended to the error, which name the field or issue it objected to. If they point at the query, correct the JQL in the Macro; if they point at permissions, either configure the instance with an account allowed to read the issues concerned, or narrow the query so that it no longer selects them.
A Generic Failure to Reach JIRA
The page shows a failure carrying the HTTP status code, the message extracted from JIRA's answer and the URL that was requested.
Cause
The request reached no JIRA at all, or JIRA answered with a status other than 400 or 401: the host or port is wrong, the instance is down or behind a proxy that intercepted the call, or the URL points at something that is not a JIRA instance.
Solution
Open the URL from the error in a browser, from the server running the wiki rather than from your own machine, and correct the "JIRA URL" of the instance definition until it answers. A status of 404 usually means the URL carries an extra path segment, since the definition expects the base URL of the instance.
No JIRA Server Found
The page shows "No JIRA Server found.", followed by the invitation to use the url or the id Macro parameter.
Cause
The Macro call names no instance: neither its url nor its id parameter is set. A single configured instance is deliberately not used as an implicit default, because adding a second one later would then break every page relying on that behaviour.
Solution
Add an id parameter to the Macro call, naming a configured instance.
The JIRA Server Id Is Not Defined
The page shows that the id used by the Macro is not defined in the configuration.
Cause
The id parameter of the Macro names an instance that the wiki administration does not define. Since definitions are per wiki, a Macro copied from another wiki of the farm produces this even though the id exists elsewhere. Deleting an instance definition produces it on every page still using its id.
Solution
Define the instance in the "JIRA" section of the administration of this wiki, or correct the id in the Macro to one that is defined.
FAQ
Why does a Macro fail while I can see all the issues in JIRA myself?
Because the wiki queries JIRA with the account configured for the instance, not with your own; that account may have fewer permissions.
Can the Macro display the issues it is allowed to read and skip the others?
No. JIRA rejects the request as a whole, so the Macro has nothing partial to display.
Does an error on one Macro break the rest of the page?
No. The error replaces that Macro's output only, and the page continues to render.
