Atlassian Troubleshooting
Match the symptom, apply the fix. Most failures come from a wrong base path (or a scoped token on the wrong host), Basic auth set up incorrectly, an expired token, an unbounded JQL, a plain string where ADF/storage is required, a stale Confluence version, or a name used where an id is required.
401 Unauthorized
Cause: bad Basic auth — wrong email, wrong/revoked/expired token, password used instead of an API token, or a scoped token sent to the site URL.
- The credential is
email:API_TOKEN, not email:account_password. Mint a token at https://id.atlassian.com/manage-profile/security/api-tokens.
- Tokens expire (1–365 days, 1 year by default). Tokens created before 2024-12-15 were given a one-year life and lapsed between 2026-03-14 and 2026-05-12, so a script that worked for years may suddenly
401 — reissue the token.
- Scoped token? (created with Create API token with scopes) It only works through the gateway:
https://api.atlassian.com/ex/jira/{cloudId}/… and https://api.atlassian.com/ex/confluence/{cloudId}/…. On https://your-domain.atlassian.net it returns 401/403. Set ATLASSIAN_CLOUD_ID (curl -s "${ATLASSIAN_SITE_URL%/}/_edge/tenant_info" | jq -r .cloudId) and use the bases from the setup skill.
- Confirm the vars are set without printing them:
[ -n "$ATLASSIAN_EMAIL" ] && [ -n "$ATLASSIAN_API_TOKEN" ] && echo set || echo MISSING.
- Re-run the
setup check: GET ${JIRA}/myself. A 200 there means auth is fine and the problem is elsewhere.
403 Forbidden (permission)
Cause: authenticated, but the token user lacks the rights for this action/object.
- Jira: run
GET /rest/api/3/mypermissions?projectKey=PROJ&permissions=CREATE_ISSUES,EDIT_ISSUES — it shows exactly which permission is missing. Scheme/admin endpoints (workflows, fields, permission schemes) need Jira admin.
- Confluence: check
GET /wiki/api/v2/pages/{id}/operations (or /spaces/{id}/operations) for what the user may do; space-restricted content needs space permission.
- Premium/Enterprise features (Advanced Roadmaps Plans, classification levels, data policies) return
403/404 when the plan doesn't include them.
- Scoped token missing a scope →
403 even for an allowed user. Compare the endpoint with the token's scopes (Jira: read:jira-work, write:jira-work, read:jira-user, …; Confluence: read:confluence-content.all, write:confluence-content, read:confluence-space.summary, …) and issue a token with the extra scope.
- A
403 is a real boundary — report it, don't try to route around it.
404 / "Not found"
Cause: wrong base path, or a name/wrong id used where a real id is required, or the object is archived/deleted.
- Base paths: Jira is
${ATLASSIAN_SITE_URL%/}/rest/api/3; Confluence v2 is ${ATLASSIAN_SITE_URL%/}/wiki/api/v2. A Confluence 404 on every call usually means the /wiki prefix is missing. With a scoped token the bases are https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3 and https://api.atlassian.com/ex/confluence/{cloudId}/wiki/api/v2.
ATLASSIAN_SITE_URL must be the site root (https://your-domain.atlassian.net) with no trailing /rest or /wiki.
- Confluence
spaceId is numeric, not the space key — resolve via GET /wiki/api/v2/spaces?keys=PROJ.
- Jira addresses issues by
issueIdOrKey (PROJ-123) — resolve a summary to a key with JQL first.
400 Validation error
Cause (Jira): malformed body, missing required field, or a plain string where ADF is expected.
- ADF, not markdown —
description and comment body must be an ADF doc: {"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"…"}]}]}. A plain string returns 400.
- Required field missing — run
GET /rest/api/3/issue/createmeta/PROJ/issuetypes/{issueTypeId} to see what's required for that type.
- Setting a field the screen doesn't include is ignored or rejected — check
GET /issue/{key}/editmeta.
- Send
-H "Content-Type: application/json" and valid JSON on every write.
Cause (Jira search): POST/GET /search/jql with an unbounded JQL — one that is only an ORDER BY (for example order by created DESC) with no restriction. Add a search restriction: created >= -30d ORDER BY created DESC, project = PROJ ORDER BY created DESC, or assignee = currentUser() ORDER BY key. Also: the ORDER BY clause may name at most 7 fields, and POST /issue/bulkfetch rejects more than 100 issues (1000 only for an explicit fields list without multi-value fields) — see search-jql.md / issues.md.
Cause (Confluence): body missing its representation, or spaceId sent as a key.
- Body must be
{"representation":"storage"|"atlas_doc_format","value":"…"}.
409 Conflict (Confluence)
Cause 1 — stale version: the version.number you sent isn't current + 1 — someone (or your own earlier call) changed the page.
- Re-read the page:
GET ${CONF}/pages/{id} → take .version.number → PUT with that number + 1. Always read-then-write.
Cause 2 — approval space (CHANGE-3432, announced 2026-09-28, rollout pending): the space requires approval before publishing. Once the change is enabled, a direct PUT /pages/{id}, PUT /pages/{id}/title (or v1 PUT /wiki/rest/api/content/{id}) on a published page returns 409 even with the correct version.number.
- A version bump will not fix it and retries will not help. Atlassian announced this on 2026-09-28 and will publish the rollout date; it applies only to regular pages in approval-enabled spaces.
- Atlassian's guidance: save the change as a draft, complete the approval, publish the approved draft. No REST draft→approval→publish flow is documented yet — use the Confluence UI or ask a Confluence admin; ask a space admin whether approvals are on if a
409 survives a correct version.
429 Too Many Requests
Cause: rate limited.
- Honor the
Retry-After response header (seconds). Inspect with curl -s -D - …; also read X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and RateLimit-Reason (for example jira-burst-based).
- API-token traffic is only under per-endpoint burst limits. The points-based hourly quotas enforced since 2026-03-02 apply to Forge, Connect and OAuth 2.0 (3LO) apps, not to API tokens — so a token script that is rate limited needs slower pacing, not a quota increase.
- Pace bulk fan-outs (mass create, bulk edit, broadcasts); add small sleeps between requests, and prefer
POST /issue/bulkfetch over one GET /issue/{key} per issue.
"CQL / full-text search doesn't work in v2"
Cause: Confluence v2 list endpoints filter by space-id/title/status only — they are not full-text search.
- Use the v1 search endpoint:
GET ${CONF_ROOT}/wiki/rest/api/search?cql=space=PROJ%20AND%20text~%22term%22.
"Label add / attachment upload returns 404/405 in v2"
Cause: those writes aren't in the Confluence v2 spec.
- Labels:
POST ${CONF_ROOT}/wiki/rest/api/content/{id}/label (v1).
- Attachment upload:
POST ${CONF_ROOT}/wiki/rest/api/content/{id}/child/attachment (v1, multipart, header X-Atlassian-Token: nocheck).
"Boards / sprints / backlog endpoint not found"
Cause: those aren't in the Jira platform API.
- They live in the Jira Software Agile REST API:
${JIRA_ROOT}/rest/agile/1.0/board, /sprint, /backlog. The bundled jira-openapi-v3.json does not cover them.
Multipart upload rejected (Jira attachments)
Cause: missing the XSRF-bypass header or sending JSON.
- Use
-F "file=@path" (not -d) and -H "X-Atlassian-Token: no-check". Do not send Content-Type: application/json for uploads.
1---2name: troubleshoot-343description: Use when a Jira or Confluence Cloud REST call fails or behaves unexpectedly - 401 or 403 with a token that looks right (expired, or scoped and sent to the site URL), 404 from a wrong base path or a missing /wiki prefix, 400 from plain-text ADF or an unbounded JQL (only ORDER BY), 409 version conflicts on page updates, 429 rate limits, Agile or v1-only endpoints missing in v2. Not for first-time credentials (setup) or ordinary calls that work (jira-operations, confluence-operations).4metadata:5 source: https://skillmd.com/skills/agents-store/troubleshoot-346---78# Atlassian Troubleshooting910Match the symptom, apply the fix. Most failures come from a wrong base path (or a scoped token on the wrong host), Basic auth set up incorrectly, an expired token, an unbounded JQL, a plain string where ADF/storage is required, a stale Confluence version, or a name used where an id is required.1112## 401 Unauthorized1314**Cause:** bad Basic auth — wrong email, wrong/revoked/**expired** token, password used instead of an API token, or a **scoped token sent to the site URL**.1516- The credential is `email:API_TOKEN`, **not** `email:account_password`. Mint a token at `https://id.atlassian.com/manage-profile/security/api-tokens`.17- **Tokens expire** (1–365 days, 1 year by default). Tokens created before 2024-12-15 were given a one-year life and lapsed between 2026-03-14 and 2026-05-12, so a script that worked for years may suddenly `401` — reissue the token.18- **Scoped token?** (created with *Create API token with scopes*) It only works through the gateway: `https://api.atlassian.com/ex/jira/{cloudId}/…` and `https://api.atlassian.com/ex/confluence/{cloudId}/…`. On `https://your-domain.atlassian.net` it returns `401`/`403`. Set `ATLASSIAN_CLOUD_ID` (`curl -s "${ATLASSIAN_SITE_URL%/}/_edge/tenant_info" | jq -r .cloudId`) and use the bases from the `setup` skill.19- Confirm the vars are set without printing them: `[ -n "$ATLASSIAN_EMAIL" ] && [ -n "$ATLASSIAN_API_TOKEN" ] && echo set || echo MISSING`.20- Re-run the `setup` check: `GET ${JIRA}/myself`. A `200` there means auth is fine and the problem is elsewhere.2122## 403 Forbidden (permission)2324**Cause:** authenticated, but the token user lacks the rights for this action/object.2526- **Jira:** run `GET /rest/api/3/mypermissions?projectKey=PROJ&permissions=CREATE_ISSUES,EDIT_ISSUES` — it shows exactly which permission is missing. Scheme/admin endpoints (workflows, fields, permission schemes) need Jira admin.27- **Confluence:** check `GET /wiki/api/v2/pages/{id}/operations` (or `/spaces/{id}/operations`) for what the user may do; space-restricted content needs space permission.28- Premium/Enterprise features (Advanced Roadmaps Plans, classification levels, data policies) return `403`/`404` when the plan doesn't include them.29- **Scoped token missing a scope** → `403` even for an allowed user. Compare the endpoint with the token's scopes (Jira: `read:jira-work`, `write:jira-work`, `read:jira-user`, …; Confluence: `read:confluence-content.all`, `write:confluence-content`, `read:confluence-space.summary`, …) and issue a token with the extra scope.30- A `403` is a real boundary — report it, don't try to route around it.3132## 404 / "Not found"3334**Cause:** wrong base path, or a name/wrong id used where a real id is required, or the object is archived/deleted.3536- **Base paths:** Jira is `${ATLASSIAN_SITE_URL%/}/rest/api/3`; Confluence v2 is `${ATLASSIAN_SITE_URL%/}/wiki/api/v2`. A Confluence `404` on every call usually means the `/wiki` prefix is missing. With a scoped token the bases are `https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3` and `https://api.atlassian.com/ex/confluence/{cloudId}/wiki/api/v2`.37- `ATLASSIAN_SITE_URL` must be the site root (`https://your-domain.atlassian.net`) with **no** trailing `/rest` or `/wiki`.38- **Confluence `spaceId` is numeric**, not the space key — resolve via `GET /wiki/api/v2/spaces?keys=PROJ`.39- **Jira** addresses issues by `issueIdOrKey` (`PROJ-123`) — resolve a summary to a key with JQL first.4041## 400 Validation error4243**Cause (Jira):** malformed body, missing required field, or a plain string where ADF is expected.4445- **ADF, not markdown** — `description` and comment `body` must be an ADF doc: `{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"…"}]}]}`. A plain string returns `400`.46- Required field missing — run `GET /rest/api/3/issue/createmeta/PROJ/issuetypes/{issueTypeId}` to see what's required for that type.47- Setting a field the screen doesn't include is ignored or rejected — check `GET /issue/{key}/editmeta`.48- Send `-H "Content-Type: application/json"` and valid JSON on every write.4950**Cause (Jira search):** `POST/GET /search/jql` with an **unbounded JQL** — one that is only an `ORDER BY` (for example `order by created DESC`) with no restriction. Add a search restriction: `created >= -30d ORDER BY created DESC`, `project = PROJ ORDER BY created DESC`, or `assignee = currentUser() ORDER BY key`. Also: the `ORDER BY` clause may name at most 7 fields, and `POST /issue/bulkfetch` rejects more than 100 issues (1000 only for an explicit `fields` list without multi-value fields) — see `search-jql.md` / `issues.md`.5152**Cause (Confluence):** body missing its `representation`, or `spaceId` sent as a key.5354- Body must be `{"representation":"storage"|"atlas_doc_format","value":"…"}`.5556## 409 Conflict (Confluence)5758**Cause 1 — stale version:** the `version.number` you sent isn't `current + 1` — someone (or your own earlier call) changed the page.5960- Re-read the page: `GET ${CONF}/pages/{id}` → take `.version.number` → `PUT` with that number `+ 1`. Always read-then-write.6162**Cause 2 — approval space (CHANGE-3432, announced 2026-09-28, rollout pending):** the space requires approval before publishing. Once the change is enabled, a direct `PUT /pages/{id}`, `PUT /pages/{id}/title` (or v1 `PUT /wiki/rest/api/content/{id}`) on a published page returns `409` **even with the correct `version.number`**.6364- A version bump will not fix it and retries will not help. Atlassian announced this on 2026-09-28 and will publish the rollout date; it applies only to regular pages in approval-enabled spaces.65- Atlassian's guidance: save the change as a draft, complete the approval, publish the approved draft. **No REST draft→approval→publish flow is documented yet** — use the Confluence UI or ask a Confluence admin; ask a space admin whether approvals are on if a `409` survives a correct version.6667## 429 Too Many Requests6869**Cause:** rate limited.7071- Honor the `Retry-After` response header (seconds). Inspect with `curl -s -D - …`; also read `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `RateLimit-Reason` (for example `jira-burst-based`).72- **API-token traffic is only under per-endpoint burst limits.** The points-based hourly quotas enforced since 2026-03-02 apply to Forge, Connect and OAuth 2.0 (3LO) apps, not to API tokens — so a token script that is rate limited needs slower pacing, not a quota increase.73- Pace bulk fan-outs (mass create, bulk edit, broadcasts); add small sleeps between requests, and prefer `POST /issue/bulkfetch` over one `GET /issue/{key}` per issue.7475## "CQL / full-text search doesn't work in v2"7677**Cause:** Confluence v2 list endpoints filter by `space-id`/`title`/`status` only — they are not full-text search.7879- Use the **v1** search endpoint: `GET ${CONF_ROOT}/wiki/rest/api/search?cql=space=PROJ%20AND%20text~%22term%22`.8081## "Label add / attachment upload returns 404/405 in v2"8283**Cause:** those writes aren't in the Confluence v2 spec.8485- Labels: `POST ${CONF_ROOT}/wiki/rest/api/content/{id}/label` (v1).86- Attachment upload: `POST ${CONF_ROOT}/wiki/rest/api/content/{id}/child/attachment` (v1, multipart, header `X-Atlassian-Token: nocheck`).8788## "Boards / sprints / backlog endpoint not found"8990**Cause:** those aren't in the Jira platform API.9192- They live in the **Jira Software Agile REST API**: `${JIRA_ROOT}/rest/agile/1.0/board`, `/sprint`, `/backlog`. The bundled `jira-openapi-v3.json` does not cover them.9394## Multipart upload rejected (Jira attachments)9596**Cause:** missing the XSRF-bypass header or sending JSON.9798- Use `-F "file=@path"` (not `-d`) **and** `-H "X-Atlassian-Token: no-check"`. Do not send `Content-Type: application/json` for uploads.