Troubleshoot

Taiga Troubleshooting

Match the symptom, apply the fix. Most Taiga API failures come from a missing version, an expired token, or using a slug where an ID is expected.

401 Unauthorized

Cause: missing, malformed, or expired TAIGA_AUTH_TOKEN.

• Confirm the header is exactly Authorization: Bearer ${TAIGA_AUTH_TOKEN} (Bearer, not Token/JWT). Application tokens instead use Authorization: Application <token>.
• If the token was valid earlier in the session, it expired — refresh it rather than re-logging in:

  export TAIGA_AUTH_TOKEN=$(curl -s -X POST "${TAIGA_API_URL%/}/api/v1/auth/refresh" \
    -H "Content-Type: application/json" -d "{\"refresh\":\"${TAIGA_REFRESH}\"}" | jq -r '.auth_token')
  

• If refresh also fails, re-run the setup login.

Login itself fails (400/401 on /auth)

• The type field is required. The body must be {"type":"normal","username":...,"password":...}. Omitting type is the most common login error.
• username accepts either the username or the email — try the other if one fails.
• Verify TAIGA_API_URL points at the instance root (no /api/v1 suffix, no trailing slash). The skill builds ${TAIGA_API_URL%/}/api/v1/auth.

400 with a "version" / "stale" / conflict message

Cause: optimistic locking. The version you sent is not the object's current version (it was edited since your GET, or you omitted version).

Fix — re-read and retry with the fresh version:

OBJ=$(curl -s -H "Authorization: Bearer ${TAIGA_AUTH_TOKEN}" "${TAIGA_API_URL%/}/api/v1/userstories/1234")
VER=$(echo "$OBJ" | jq -r .version)
curl -s -X PATCH -H "Authorization: Bearer ${TAIGA_AUTH_TOKEN}" -H "Content-Type: application/json" \
  -d "{\"subject\":\"Updated\",\"version\":${VER}}" "${TAIGA_API_URL%/}/api/v1/userstories/1234"

Every PATCH/PUT on items, statuses, attachments, and custom-attribute values needs the current version.

403 Forbidden

Cause: authenticated but the role lacks the permission, or the object is in a private project you can't access.

• Check the user's role permissions: GET /roles/{id} and GET /permissions. (→ api-reference projects.md)
• Admin-only operations (e.g. GET /stats/system, deleting others' content) require a superuser/owner account — the TAIGA_ADMIN_* credentials should map to one.

404 / "object not found"

Cause: usually a slug or reference number used where a numeric ID is required.

• Refs like #42 and project slugs are not IDs. Resolve first:

  curl -s -H "Authorization: Bearer ${TAIGA_AUTH_TOKEN}" \
    "${TAIGA_API_URL%/}/api/v1/resolver?project=my-slug&us=42" | jq .
  

• Or use the dedicated by_ref endpoints: GET /userstories/by_ref?ref=42&project=<id> (same for tasks, issues, epics).

A list seems to be missing rows

Cause: pagination. List endpoints return one page by default.

• Inspect headers: curl -s -D - ... | grep -i x-pagination. x-pagination-count is the true total.
• Walk pages with ?page=2, ?page=3, … or fetch everything in one go with header x-disable-pagination: True (use carefully on large projects).

Creating an item rejects a status / type / priority / severity

Cause: those IDs are per-project. An ID valid in one project is invalid in another.

• Discover valid values: GET /<resource>/filters_data?project=<id> or GET /<resource>-statuses?project=<id>. Pick the ID for that project.

Tags don't apply

Tags are arrays of [name, color] pairs, e.g. "tags": [["urgent","#ff0000"],["backend",null]] — not bare strings. Project-level tag management uses /projects/{id}/create_tag etc. (→ projects.md).

Optional convenience MCP

If you'd rather call tools than curl for the ~33 most common operations, the community greddy7574/taiga-mcp-server (npx) and talhaorak/pytaiga-mcp exist. They cover a subset only — for full coverage use the REST endpoints in api-reference. These are not dependencies of this plugin.