Troubleshooting

This page is a symptom index for the issues you're most likely to hit when integrating with the Atlassian A2A Gateway. To confirm the endpoints respond at all, run the checks in Debugging first.

---

Common response codes

---

Connection and discovery issues

Agent Card returns unexpected content

Symptom: The Agent Card response doesn't match what you expect, or contains different skills than documented.

Possible causes:

1. Cached card — The Agent Card is cached for 5 minutes. If the agent's configuration was recently updated, wait for the cache to expire and request the card again.
2. Static fallback is being served — If the downstream Rovo service is temporarily unavailable, the gateway serves a built-in fallback card. It advertises the same endpoint, the same authentication configuration, and a valid baseline of skills, so your requests continue to work.

Resolution: Both cards are safe to use, so this is not a blocking condition. Request the Agent Card again after the 5-minute cache window has passed. If the content still doesn't match this documentation, contact Atlassian support.

JSON-RPC endpoint returns 404

Symptom: POST requests to https://a2a.atlassian.com/v1/rovo return 404 Not Found.

Possible causes:

1. Wrong URL — Ensure you're using the correct endpoint path (/v1/rovo).
2. Wrong HTTP method — The endpoint only accepts POST. GET requests return 404.

Resolution:

• Verify you're using the production URL: https://a2a.atlassian.com/v1/rovo with POST.

---

Authentication issues

Authentication is rejected before task execution

Symptom: Requests to the JSON-RPC endpoint are rejected before you receive a task response. Depending on the auth layer in front of the gateway, this may appear as 401 Unauthorized.

Possible causes:

1. Missing access token — The Authorization: Bearer <token> header is not included.
2. Expired access token — OAuth access tokens have a limited lifespan.
3. Invalid token — The token was revoked or is malformed.
4. Wrong auth method — A2A only supports OAuth 2.0 access tokens. API tokens and session cookies are not accepted.

Resolution:

• Ensure the Authorization: Bearer <token> header is present.
• Use your refresh token to obtain a new access token (see Authentication: Refreshing access tokens).
• Verify you're using an OAuth 2.0 access token, not an API token.

403 — A2A disabled by admin (error code -32007)

Symptom: Requests return a 403 with error code -32007 and the message "A2A connections are not enabled for this organization."

Cause: An administrator has not enabled A2A. A2A connections are disabled by default.

Receiving this code confirms the gateway identified your organization. If it could not, you would get -32008 instead.

Resolution:

• Ask your organization administrator to enable A2A for the organization.

403 with error code -32008 (organization cannot be resolved)

Symptom: Requests return a 403 with error code -32008 and the message "Unable to determine the organization for the requested site."

Cause: The gateway derives your organization from the Atlassian site associated with your access token. This error means either the token carried no site, or the site could not be mapped to an organization. The organization is resolved before the admin setting is checked, so this error replaces -32007 rather than accompanying it.

Resolution:

• Re-authorize the A2A connection to refresh the session context.
• If the error persists, the site may not be correctly associated with an organization. Contact your Atlassian site administrator, since this cannot be corrected from the client.

OAuth consent flow fails

Symptom: The user cannot complete the OAuth consent flow, or the browser shows an error.

Possible causes:

1. Missing PKCE — The authorization request omitted code_challenge and code_challenge_method=S256. The consent page shows "Hmm... We're having trouble logging you in." with the message "This app requires enhanced security (PKCE) to continue. Contact the app developer."
2. Missing scopes — The OAuth app doesn't request the required A2A scopes.
3. Invalid redirect URI — The callback URL doesn't match the registered OAuth app.
4. User lacks access — The user doesn't have access to the Atlassian products required by the scopes.

Resolution:

• Send code_challenge and code_challenge_method=S256 on the authorization request, and the matching code_verifier on the token exchange. PKCE is required and the flow cannot complete without it.
• Verify the OAuth app is configured with the correct scopes: read:me, offline_access, full_access:chat:rovo.
• Ensure the redirect URI matches exactly.
• Confirm the user has an active Atlassian Cloud account with Rovo access.

---

Request and response issues

Invalid JSON-RPC request (error code -32600)

Symptom: Response contains error code -32600 with a message about invalid request structure.

Possible causes:

1. Missing jsonrpc field — Must be "2.0".
2. Missing or invalid id — Must be a string or number.
3. Missing method — Must be a string.

Resolution: Ensure your request follows the JSON-RPC 2.0 format:

1
2
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "message/send",
  "params": { ... }
}

Invalid params (error code -32602)

Symptom: Response contains error code -32602.

Cause: The downstream Rovo service rejected the shape of your params. The gateway forwards this error unchanged, so the code originates downstream rather than at the gateway.

Possible reasons:

1. Missing message object — The params must contain a message field.
2. Missing parts — The message must contain at least one part.
3. Invalid role — Must be "user" or "agent".

Resolution: Ensure your message follows the required format:

1
2
{
  "params": {
    "message": {
      "kind": "message",
      "messageId": "22222222-2222-4222-8222-222222222222",
      "role": "user",
      "parts": [{ "kind": "text", "text": "Your message here" }]
    }
  }
}

Request times out after about 30 seconds (HTTP 500)

message/send returns a single response after Rovo finishes the task. Requests that run longer than roughly 30 seconds can be terminated at the network edge with an HTTP 500 before Rovo finishes. That limit is enforced by the CDN rather than by the gateway, so treat the number as approximate. Use message/stream for any request that may run longer, including multi-step work.

Symptom: an HTTP 500 is returned roughly 30 seconds after sending a message/send request. The gateway and Rovo are healthy; the response is cut off before Rovo finishes.

Fix: resend the request using message/stream and consume the SSE event stream until the task reaches a terminal state.

Task result is failed

Symptom: The HTTP response is 200, but result.status.state is "failed".

Possible causes:

1. Rovo backend error — The downstream Rovo service could not complete the request.
2. No usable text content — The request did not include a non-empty text part.
3. Permission issue — The authenticated user does not have access to the requested Jira or Confluence content.

Resolution:

• Check result.status.message.parts for the failure text returned by the gateway.
• Ensure your request includes at least one non-empty text part.
• Confirm the authenticated user can access the referenced Atlassian resources in the UI.

Agent invocation failed (error code -32006)

Symptom: Response contains error code -32006 with "Agent invocation failed."

Possible causes:

1. Unexpected downstream response — The gateway could not parse a valid text response from Rovo.
2. Gateway-side processing issue — An unexpected error occurred while preparing or handling the downstream request.

Resolution:

• Retry the request if the failure appears transient.
• Inspect the error.data payload if present - it may include the failed task returned by the gateway.
• If the issue persists, contact Atlassian support.

---

Getting help

If you need assistance with A2A integration:

1. Match the status code you received against the Common response codes table at the top of this page.
2. Use Debugging to re-run the verification commands against the live endpoints.
3. Review Authentication and Architecture to confirm your setup matches the current gateway behavior.
4. Contact Atlassian support for customer-facing issues.

Next steps

• Authentication — Fix auth and org enablement issues.
• Architecture — Review the request flow and current method support.
• Getting started — Validate the happy path from discovery to first request.
• Debugging — Re-run the quick verification commands against the live endpoints.