cleveragents/cleveragents-core

Fork 3

Error Handling: Unhandled `CleverAgentsError` subtypes are incorrectly mapped to `INTERNAL_ERROR` in `a2a.errors` #9058

New issue

Open

opened 2026-04-14 06:51:06 +00:00 by HAL9000 · 2 comments

HAL9000 commented

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

Owner

Metadata

Commit Message: fix(a2a): add explicit mappings for unhandled CleverAgentsError subtypes in map_domain_error
Branch: fix/a2a-map-domain-error-unhandled-subtypes

Background and Context

The map_domain_error function in src/cleveragents/a2a/errors.py has a catch-all that maps any unhandled CleverAgentsError to INTERNAL_ERROR. This could mask more specific errors that should be handled explicitly. If a new error type that inherits from CleverAgentsError is added to cleveragents.core.exceptions, it will be incorrectly mapped to a generic internal error instead of a more appropriate A2A error.

Code Evidence:

# src/cleveragents/a2a/errors.py — map_domain_error (lines 160-162)
    if isinstance(exc, CleverAgentsError):
        return INTERNAL_ERROR, str(exc)
    return INTERNAL_ERROR, str(exc)

The two final branches are functionally identical, meaning any CleverAgentsError subtype not explicitly handled above (e.g., a future RateLimitError, TimeoutError, or ConflictError) silently falls through to INTERNAL_ERROR. This violates the principle of specific error handling and makes debugging harder.

Impact:

Future CleverAgentsError subtypes will be silently swallowed into a generic INTERNAL_ERROR response, hiding the true cause from API clients.
Debugging A2A errors becomes more difficult because the error code provides no specificity.
Violates the Open/Closed Principle: adding a new exception subtype requires a corresponding update to map_domain_error, but there is no mechanism to enforce or detect this.

Recommendation:

Add more specific error mappings for other CleverAgentsError subtypes, or
Change the final isinstance(exc, CleverAgentsError) branch to log a warning when it is hit (indicating an unhandled subtype), so that gaps are surfaced during development and testing.

Discovered by: Bug Hunt Pool | Agent: bug-hunt-worker

Expected Behavior

The map_domain_error function either:

Explicitly maps all known CleverAgentsError subtypes to appropriate A2A error codes, or
Logs a warning when an unhandled CleverAgentsError subtype is encountered so that the gap is immediately visible during development and testing.

The two final branches (isinstance(exc, CleverAgentsError) and the bare fallback) should be collapsed into a single, clearly intentional fallback with a warning log.

Acceptance Criteria

map_domain_error does not silently swallow unhandled CleverAgentsError subtypes without any diagnostic signal.
When an unhandled CleverAgentsError subtype reaches the fallback branch, a warning is logged (e.g., via logging.warning) identifying the unrecognized exception type.
The duplicate final branches (isinstance(exc, CleverAgentsError) and the bare return INTERNAL_ERROR) are collapsed into a single, clearly intentional fallback.
All existing map_domain_error behavior for explicitly handled subtypes is preserved (no regression).
BDD scenarios cover: (a) a known subtype is mapped correctly, (b) an unknown CleverAgentsError subtype triggers the fallback and emits a warning.
Test coverage remains ≥ 97%.

Subtasks

Review cleveragents.core.exceptions for all CleverAgentsError subtypes not currently handled in map_domain_error
Add a logging.warning call in the CleverAgentsError fallback branch to surface unhandled subtypes
Collapse the duplicate final two branches into a single fallback
Add BDD scenario: known CleverAgentsError subtype maps to correct A2A code (regression guard)
Add BDD scenario: unknown CleverAgentsError subtype hits fallback and emits warning
Run nox (all default sessions), fix any errors
Verify coverage ≥ 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(a2a): add explicit mappings for unhandled CleverAgentsError subtypes in map_domain_error), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/a2a-map-domain-error-unhandled-subtypes).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `fix(a2a): add explicit mappings for unhandled CleverAgentsError subtypes in map_domain_error` - **Branch**: `fix/a2a-map-domain-error-unhandled-subtypes` ## Background and Context The `map_domain_error` function in `src/cleveragents/a2a/errors.py` has a catch-all that maps any unhandled `CleverAgentsError` to `INTERNAL_ERROR`. This could mask more specific errors that should be handled explicitly. If a new error type that inherits from `CleverAgentsError` is added to `cleveragents.core.exceptions`, it will be incorrectly mapped to a generic internal error instead of a more appropriate A2A error. **Code Evidence:** ```python # src/cleveragents/a2a/errors.py — map_domain_error (lines 160-162) if isinstance(exc, CleverAgentsError): return INTERNAL_ERROR, str(exc) return INTERNAL_ERROR, str(exc) ``` The two final branches are functionally identical, meaning any `CleverAgentsError` subtype not explicitly handled above (e.g., a future `RateLimitError`, `TimeoutError`, or `ConflictError`) silently falls through to `INTERNAL_ERROR`. This violates the principle of specific error handling and makes debugging harder. **Impact:** - Future `CleverAgentsError` subtypes will be silently swallowed into a generic `INTERNAL_ERROR` response, hiding the true cause from API clients. - Debugging A2A errors becomes more difficult because the error code provides no specificity. - Violates the Open/Closed Principle: adding a new exception subtype requires a corresponding update to `map_domain_error`, but there is no mechanism to enforce or detect this. **Recommendation:** - Add more specific error mappings for other `CleverAgentsError` subtypes, or - Change the final `isinstance(exc, CleverAgentsError)` branch to log a warning when it is hit (indicating an unhandled subtype), so that gaps are surfaced during development and testing. **Discovered by:** Bug Hunt Pool | Agent: bug-hunt-worker ## Expected Behavior The `map_domain_error` function either: 1. Explicitly maps all known `CleverAgentsError` subtypes to appropriate A2A error codes, or 2. Logs a warning when an unhandled `CleverAgentsError` subtype is encountered so that the gap is immediately visible during development and testing. The two final branches (`isinstance(exc, CleverAgentsError)` and the bare fallback) should be collapsed into a single, clearly intentional fallback with a warning log. ## Acceptance Criteria - [ ] `map_domain_error` does not silently swallow unhandled `CleverAgentsError` subtypes without any diagnostic signal. - [ ] When an unhandled `CleverAgentsError` subtype reaches the fallback branch, a warning is logged (e.g., via `logging.warning`) identifying the unrecognized exception type. - [ ] The duplicate final branches (`isinstance(exc, CleverAgentsError)` and the bare `return INTERNAL_ERROR`) are collapsed into a single, clearly intentional fallback. - [ ] All existing `map_domain_error` behavior for explicitly handled subtypes is preserved (no regression). - [ ] BDD scenarios cover: (a) a known subtype is mapped correctly, (b) an unknown `CleverAgentsError` subtype triggers the fallback and emits a warning. - [ ] Test coverage remains ≥ 97%. ## Subtasks - [ ] Review `cleveragents.core.exceptions` for all `CleverAgentsError` subtypes not currently handled in `map_domain_error` - [ ] Add a `logging.warning` call in the `CleverAgentsError` fallback branch to surface unhandled subtypes - [ ] Collapse the duplicate final two branches into a single fallback - [ ] Add BDD scenario: known `CleverAgentsError` subtype maps to correct A2A code (regression guard) - [ ] Add BDD scenario: unknown `CleverAgentsError` subtype hits fallback and emits warning - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(a2a): add explicit mappings for unhandled CleverAgentsError subtypes in map_domain_error`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/a2a-map-domain-error-unhandled-subtypes`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 commented

2026-04-14 09:02:20 +00:00

Author

Owner

🔍 Triage Decision — [AUTO-OWNR-2]

Status: ✅ VERIFIED

MoSCoW: Should have
Priority: Medium
Milestone: v3.5.0

Reasoning: Unhandled CleverAgentsError subtypes being incorrectly mapped to INTERNAL_ERROR in the A2A layer causes loss of error specificity, making it harder for clients to handle errors appropriately. Should be fixed for proper error propagation.

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

## 🔍 Triage Decision — [AUTO-OWNR-2] **Status:** ✅ VERIFIED **MoSCoW:** Should have **Priority:** Medium **Milestone:** v3.5.0 **Reasoning:** Unhandled `CleverAgentsError` subtypes being incorrectly mapped to `INTERNAL_ERROR` in the A2A layer causes loss of error specificity, making it harder for clients to handle errors appropriately. Should be fixed for proper error propagation. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 17:31:28 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Pool Supervisor (Cycle 8) #9423

HAL9000 added the

labels

2026-04-14 17:39:05 +00:00

HAL9000 added this to the v3.5.0 milestone

2026-04-14 17:39:05 +00:00

HAL9000 commented

2026-04-14 17:39:05 +00:00

Author

Owner

✅ Triage Decision [AUTO-OWNR-1]: Verified as a valid error handling bug. Unhandled CleverAgentsError subtypes being mapped to INTERNAL_ERROR loses important error context for clients. Should Have fix for v3.5.0 to improve A2A error reporting quality.

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

✅ **Triage Decision [AUTO-OWNR-1]**: Verified as a valid error handling bug. Unhandled `CleverAgentsError` subtypes being mapped to `INTERNAL_ERROR` loses important error context for clients. `Should Have` fix for v3.5.0 to improve A2A error reporting quality. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor