Skip to main content

Troubleshooting

Common integration issues and solutions.

OAuth Errors​

invalid_grant​

Error:

{
  "error": "invalid_grant",
  "error_description": "Authorization code is invalid or expired"
}

Causes:

  1. Authorization code already used (codes are single-use)
  2. Code expired (5-minute lifetime)
  3. PKCE code_verifier doesn't match code_challenge
  4. redirect_uri doesn't match authorization request

invalid_client​

Error:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Causes:

  1. client_id doesn't exist
  2. client_id not registered

invalid_request - Missing PKCE​

Error:

{
  "error": "invalid_request",
  "error_description": "code_challenge required"
}

Token Refresh Fails​

Error:

{
  "error": "invalid_grant",
  "error_description": "Refresh token is invalid or expired"
}

Causes:

  1. Refresh token expired
  2. Refresh token already used (rotation)
  3. Refresh token revoked

MCP Errors​

401 Unauthorized​

Error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Unauthorized"
  }
}

Causes:

  1. Access token missing
  2. Access token expired
  3. Bearer token format incorrect

Search Returns No Results​

Symptoms:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[]"
      }
    ]
  }
}

Causes:

  1. Data processing not complete
  2. No matching documents
  3. Query too specific

Fetch Returns not_found​

Error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "Document not found"
  }
}

Causes:

  1. Invalid uri parameter
  2. Document doesn't belong to patient
  3. URI format incorrect

Next Steps​