cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [error-handling] map_domain_error() misclassifies A2aVersionMismatchError as INTERNAL_ERROR (-32603) instead of VERSION_MISMATCH (-32007) #7735

New issue

Open

opened 2026-04-12 03:21:52 +00:00 by HAL9000 · 3 comments

HAL9000 commented

2026-04-12 03:21:52 +00:00

Owner

Bug Report: [Error Handling] — A2aVersionMismatchError Returns Wrong JSON-RPC Error Code

Severity Assessment

Impact: Version negotiation failures are returned to A2A clients with error code -32603 (INTERNAL_ERROR) instead of -32007 (VERSION_MISMATCH). Clients that inspect the error code to decide on retry/fallback behavior will misinterpret version incompatibilities as internal server errors
Likelihood: High — every failed version negotiation (e.g. unsupported client version) triggers this
Priority: High

Location

File: src/cleveragents/a2a/errors.py
Function/Class: map_domain_error() and module-level constants
Lines: ~43–103

Description

The error taxonomy documented in the module comments defines -32007 for version mismatch. However:

The constant VERSION_MISMATCH = -32007 is never defined in the module despite being documented
map_domain_error() has no isinstance(exc, A2aVersionMismatchError) case
A2aVersionMismatchError inherits from A2aError → CleverAgentsError, so it falls through to the CleverAgentsError catch-all which returns -32603 (INTERNAL_ERROR)

This is a spec alignment bug: the A2A protocol taxonomy explicitly reserves -32007 for version mismatch errors.

Evidence

# errors.py — documented in comments but never defined:
# -32007  Version mismatch

# Defined constants (VERSION_MISMATCH = -32007 is MISSING):
NOT_FOUND: int = -32001
AUTH_ERROR: int = -32002
FORBIDDEN: int = -32003
INVALID_STATE: int = -32004
# -32005, -32006, -32007 are all missing!
PLAN_ERROR: int = -32008
CONFIGURATION_ERROR: int = -32009

# map_domain_error() — no case for A2aVersionMismatchError:
def map_domain_error(exc: Exception) -> tuple[int, str]:
    if isinstance(exc, ResourceNotFoundError):
        return NOT_FOUND, str(exc)
    # ... other cases ...
    if isinstance(exc, CleverAgentsError):   # <-- A2aVersionMismatchError matches HERE
        return INTERNAL_ERROR, str(exc)       # returns -32603, wrong!
    return INTERNAL_ERROR, str(exc)

# A2aVersionMismatchError inheritance chain:
class A2aVersionMismatchError(A2aError):   # A2aError → CleverAgentsError
    ...

Expected Behavior

map_domain_error(A2aVersionMismatchError(...)) should return (-32007, message). The constant VERSION_MISMATCH = -32007 should be defined and exported.

Actual Behavior

map_domain_error(A2aVersionMismatchError(...)) returns (-32603, message) because the exception falls through the CleverAgentsError catch-all.

Suggested Fix

# Add missing constant
VERSION_MISMATCH: int = -32007

# Add case before the CleverAgentsError catch-all in map_domain_error():
from cleveragents.a2a.errors import A2aVersionMismatchError  # or handle via circular-import guard

if isinstance(exc, A2aVersionMismatchError):
    return VERSION_MISMATCH, str(exc)
if isinstance(exc, CleverAgentsError):
    return INTERNAL_ERROR, str(exc)

Note: To avoid circular imports, the check can use the class name string or be placed in a separate mapping module.

TDD Note

After this bug issue is verified, a corresponding Type/Testing issue will be created for TDD.

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: bug-hunter

## Bug Report: [Error Handling] — A2aVersionMismatchError Returns Wrong JSON-RPC Error Code ### Severity Assessment - **Impact**: Version negotiation failures are returned to A2A clients with error code -32603 (INTERNAL_ERROR) instead of -32007 (VERSION_MISMATCH). Clients that inspect the error code to decide on retry/fallback behavior will misinterpret version incompatibilities as internal server errors - **Likelihood**: High — every failed version negotiation (e.g. unsupported client version) triggers this - **Priority**: High ### Location - **File**: `src/cleveragents/a2a/errors.py` - **Function/Class**: `map_domain_error()` and module-level constants - **Lines**: ~43–103 ### Description The error taxonomy documented in the module comments defines -32007 for version mismatch. However: 1. The constant `VERSION_MISMATCH = -32007` is **never defined** in the module despite being documented 2. `map_domain_error()` has no `isinstance(exc, A2aVersionMismatchError)` case 3. `A2aVersionMismatchError` inherits from `A2aError → CleverAgentsError`, so it falls through to the `CleverAgentsError` catch-all which returns `-32603` (INTERNAL_ERROR) This is a spec alignment bug: the A2A protocol taxonomy explicitly reserves -32007 for version mismatch errors. ### Evidence ```python # errors.py — documented in comments but never defined: # -32007 Version mismatch # Defined constants (VERSION_MISMATCH = -32007 is MISSING): NOT_FOUND: int = -32001 AUTH_ERROR: int = -32002 FORBIDDEN: int = -32003 INVALID_STATE: int = -32004 # -32005, -32006, -32007 are all missing! PLAN_ERROR: int = -32008 CONFIGURATION_ERROR: int = -32009 # map_domain_error() — no case for A2aVersionMismatchError: def map_domain_error(exc: Exception) -> tuple[int, str]: if isinstance(exc, ResourceNotFoundError): return NOT_FOUND, str(exc) # ... other cases ... if isinstance(exc, CleverAgentsError): # <-- A2aVersionMismatchError matches HERE return INTERNAL_ERROR, str(exc) # returns -32603, wrong! return INTERNAL_ERROR, str(exc) # A2aVersionMismatchError inheritance chain: class A2aVersionMismatchError(A2aError): # A2aError → CleverAgentsError ... ``` ### Expected Behavior `map_domain_error(A2aVersionMismatchError(...))` should return `(-32007, message)`. The constant `VERSION_MISMATCH = -32007` should be defined and exported. ### Actual Behavior `map_domain_error(A2aVersionMismatchError(...))` returns `(-32603, message)` because the exception falls through the `CleverAgentsError` catch-all. ### Suggested Fix ```python # Add missing constant VERSION_MISMATCH: int = -32007 # Add case before the CleverAgentsError catch-all in map_domain_error(): from cleveragents.a2a.errors import A2aVersionMismatchError # or handle via circular-import guard if isinstance(exc, A2aVersionMismatchError): return VERSION_MISMATCH, str(exc) if isinstance(exc, CleverAgentsError): return INTERNAL_ERROR, str(exc) ``` Note: To avoid circular imports, the check can use the class name string or be placed in a separate mapping module. ### Category error-handling ### TDD Note After this bug issue is verified, a corresponding Type/Testing issue will be created for TDD. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: bug-hunter

HAL9000 added this to the v3.2.0 milestone

2026-04-12 03:46:39 +00:00

HAL9000 referenced this issue

2026-04-12 03:47:56 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 1) #7724

HAL9000 added the

labels

2026-04-12 07:15:56 +00:00

freemo added the

Type

Bug

label

2026-04-12 18:33:51 +00:00

HAL9000 added

and removed

labels

2026-04-14 05:58:43 +00:00

HAL9000 commented

2026-04-14 05:58:43 +00:00

Author

Owner

✅ Verified — Bug: map_domain_error() misclassifies A2aVersionMismatchError as INTERNAL_ERROR. MoSCoW: Should-have. Priority: Medium.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — Bug: map_domain_error() misclassifies A2aVersionMismatchError as INTERNAL_ERROR. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

2026-04-14 06:12:00 +00:00

Author

Owner

✅ Verified — Bug: map_domain_error() misclassifies A2aVersionMismatchError as INTERNAL_ERROR. MoSCoW: Should-have. Priority: Medium.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor