Wiki source code of JIRA Connection Errors
Last modified by Vincent Massol on 2026/07/27 21:23
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 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. | ||
| 2 | |||
| 3 | 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. | ||
| 4 | |||
| 5 | == JIRA Returned an Error of the Request == | ||
| 6 | |||
| 7 | 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. | ||
| 8 | |||
| 9 | === Cause === | ||
| 10 | |||
| 11 | 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. | ||
| 12 | |||
| 13 | === Solution === | ||
| 14 | |||
| 15 | 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. | ||
| 16 | |||
| 17 | == A Generic Failure to Reach JIRA == | ||
| 18 | |||
| 19 | The page shows a failure carrying the HTTP status code, the message extracted from JIRA's answer and the URL that was requested. | ||
| 20 | |||
| 21 | === Cause === | ||
| 22 | |||
| 23 | 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. | ||
| 24 | |||
| 25 | === Solution === | ||
| 26 | |||
| 27 | 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. | ||
| 28 | |||
| 29 | == No JIRA Server Found == | ||
| 30 | |||
| 31 | The page shows "No JIRA Server found.", followed by the invitation to use the ##url## or the ##id## Macro parameter. | ||
| 32 | |||
| 33 | === Cause === | ||
| 34 | |||
| 35 | 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. | ||
| 36 | |||
| 37 | === Solution === | ||
| 38 | |||
| 39 | Add an ##id## parameter to the Macro call, naming a configured instance. | ||
| 40 | |||
| 41 | == The JIRA Server Id Is Not Defined == | ||
| 42 | |||
| 43 | The page shows that the id used by the Macro is not defined in the configuration. | ||
| 44 | |||
| 45 | === Cause === | ||
| 46 | |||
| 47 | 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. | ||
| 48 | |||
| 49 | === Solution === | ||
| 50 | |||
| 51 | 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. |
