fix(error-handling): replace broad `except Exception` clauses in agents module with specific exception handlers #3447

New issue

Open

opened 2026-04-05 17:08:15 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 17:08:15 +00:00

Owner

Metadata

Branch: fix/error-handling-agents-broad-except
Commit Message: fix(error-handling): replace broad except Exception clauses in agents module with specific handlers
Milestone: Backlog
Parent Epic: #362

Background and Context

A bug-hunt audit of the agents module identified multiple locations where broad except Exception clauses are used as catch-all handlers. This pattern violates the project's error-handling standards (CONTRIBUTING.md: "Exceptions should only be caught for meaningful recovery logic, not just for logging") and can silently swallow unexpected errors, making bugs extremely difficult to diagnose.

The affected files and functions are:

File	Function	Line	Pattern
`src/cleveragents/agents/graphs/auto_debug.py`	`_validate_fix`	232	Catches all exceptions, silently sets `is_valid = True`
`src/cleveragents/agents/graphs/context_analysis.py`	`_load_files`	262	Catches all exceptions, appends generic error string
`src/cleveragents/agents/graphs/context_analysis.py`	`_analyze_dependencies`	293	Catches all exceptions, silently returns empty list
`src/cleveragents/agents/graphs/context_analysis.py`	`_score_relevance`	351	Catches all exceptions, silently returns default score 0.5
`src/cleveragents/agents/graphs/context_analysis.py`	`_summarize_context`	390	Catches all exceptions, silently falls back to current error
`src/cleveragents/agents/graphs/plan_generation.py`	`_analyze_requirements`	411	Catches all exceptions, returns error dict
`src/cleveragents/agents/graphs/plan_generation.py`	`_generate_plan`	461	Catches all exceptions, returns error dict
`src/cleveragents/agents/graphs/plan_generation.py`	`_validate`	562	Catches all exceptions, returns FAIL status
`src/cleveragents/agents/graphs/plan_generation.py`	`_analyze_contexts`	621	Catches all exceptions, silently uses fallback summary

Current Behavior

All nine locations use except Exception (or except Exception as exc/e) as a broad catch-all. This means programming errors (e.g., AttributeError, TypeError, KeyError) are silently swallowed alongside expected I/O or LLM errors, making bugs invisible in production.

Expected Behavior

Each catch site should enumerate only the specific exception types that represent known, recoverable failure modes (e.g., OSError, FileNotFoundError, json.JSONDecodeError, LangChainException, etc.). Unexpected exceptions should propagate so they surface in logs and monitoring.

Acceptance Criteria

All nine broad except Exception clauses are replaced with specific, documented exception types
Each handler includes a comment explaining why that specific exception is caught and how recovery is performed
No new broad except Exception clauses are introduced
All existing unit tests continue to pass (nox -e unit_tests)
A TDD issue-capture Behave scenario tagged @tdd_expected_fail is added for each affected function before the fix is applied
nox -e typecheck passes with no new errors
nox -e lint passes with no new errors
Coverage remains ≥ 97% (nox -e coverage_report)

Subtasks

Add @tdd_expected_fail Behave scenarios in features/ capturing the broad-except bug for each of the 9 affected functions
Audit each catch site and document the specific exception types that are legitimately expected
Replace except Exception in auto_debug.py:_validate_fix (line 232) with specific LLM/network exception types
Replace except Exception in context_analysis.py:_load_files (line 262) with OSError, FileNotFoundError, PermissionError, etc.
Replace except Exception in context_analysis.py:_analyze_dependencies (line 293) with specific parser/IO exception types
Replace except Exception in context_analysis.py:_score_relevance (line 351) with specific exception types
Replace except Exception in context_analysis.py:_summarize_context (line 390) with specific exception types
Replace except Exception in plan_generation.py:_analyze_requirements (line 411) with specific exception types
Replace except Exception in plan_generation.py:_generate_plan (line 461) with specific exception types
Replace except Exception in plan_generation.py:_validate (line 562) with specific exception types
Replace except Exception in plan_generation.py:_analyze_contexts (line 621) with specific exception types
Remove # pragma: no cover - defensive comments where the new specific handlers are now testable
Run full nox suite and confirm all gates pass

Definition of Done

All subtasks above are checked
All nine broad except Exception clauses replaced with specific handlers
TDD issue-capture scenarios exist and pass after the fix
Commit pushed to fix/error-handling-agents-broad-except with message: fix(error-handling): replace broad except Exception clauses in agents module with specific handlers
PR merged and linked to this issue
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.3.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/error-handling-agents-broad-except` - **Commit Message**: `fix(error-handling): replace broad except Exception clauses in agents module with specific handlers` - **Milestone**: Backlog - **Parent Epic**: #362 ## Background and Context A bug-hunt audit of the agents module identified multiple locations where broad `except Exception` clauses are used as catch-all handlers. This pattern violates the project's error-handling standards (CONTRIBUTING.md: *"Exceptions should only be caught for meaningful recovery logic, not just for logging"*) and can silently swallow unexpected errors, making bugs extremely difficult to diagnose. The affected files and functions are: | File | Function | Line | Pattern | |------|----------|------|---------| | `src/cleveragents/agents/graphs/auto_debug.py` | `_validate_fix` | 232 | Catches all exceptions, silently sets `is_valid = True` | | `src/cleveragents/agents/graphs/context_analysis.py` | `_load_files` | 262 | Catches all exceptions, appends generic error string | | `src/cleveragents/agents/graphs/context_analysis.py` | `_analyze_dependencies` | 293 | Catches all exceptions, silently returns empty list | | `src/cleveragents/agents/graphs/context_analysis.py` | `_score_relevance` | 351 | Catches all exceptions, silently returns default score 0.5 | | `src/cleveragents/agents/graphs/context_analysis.py` | `_summarize_context` | 390 | Catches all exceptions, silently falls back to current error | | `src/cleveragents/agents/graphs/plan_generation.py` | `_analyze_requirements` | 411 | Catches all exceptions, returns error dict | | `src/cleveragents/agents/graphs/plan_generation.py` | `_generate_plan` | 461 | Catches all exceptions, returns error dict | | `src/cleveragents/agents/graphs/plan_generation.py` | `_validate` | 562 | Catches all exceptions, returns FAIL status | | `src/cleveragents/agents/graphs/plan_generation.py` | `_analyze_contexts` | 621 | Catches all exceptions, silently uses fallback summary | ## Current Behavior All nine locations use `except Exception` (or `except Exception as exc/e`) as a broad catch-all. This means programming errors (e.g., `AttributeError`, `TypeError`, `KeyError`) are silently swallowed alongside expected I/O or LLM errors, making bugs invisible in production. ## Expected Behavior Each catch site should enumerate only the specific exception types that represent known, recoverable failure modes (e.g., `OSError`, `FileNotFoundError`, `json.JSONDecodeError`, `LangChainException`, etc.). Unexpected exceptions should propagate so they surface in logs and monitoring. ## Acceptance Criteria - [ ] All nine broad `except Exception` clauses are replaced with specific, documented exception types - [ ] Each handler includes a comment explaining why that specific exception is caught and how recovery is performed - [ ] No new broad `except Exception` clauses are introduced - [ ] All existing unit tests continue to pass (`nox -e unit_tests`) - [ ] A TDD issue-capture Behave scenario tagged `@tdd_expected_fail` is added for each affected function before the fix is applied - [ ] `nox -e typecheck` passes with no new errors - [ ] `nox -e lint` passes with no new errors - [ ] Coverage remains ≥ 97% (`nox -e coverage_report`) ## Subtasks - [ ] Add `@tdd_expected_fail` Behave scenarios in `features/` capturing the broad-except bug for each of the 9 affected functions - [ ] Audit each catch site and document the specific exception types that are legitimately expected - [ ] Replace `except Exception` in `auto_debug.py:_validate_fix` (line 232) with specific LLM/network exception types - [ ] Replace `except Exception` in `context_analysis.py:_load_files` (line 262) with `OSError`, `FileNotFoundError`, `PermissionError`, etc. - [ ] Replace `except Exception` in `context_analysis.py:_analyze_dependencies` (line 293) with specific parser/IO exception types - [ ] Replace `except Exception` in `context_analysis.py:_score_relevance` (line 351) with specific exception types - [ ] Replace `except Exception` in `context_analysis.py:_summarize_context` (line 390) with specific exception types - [ ] Replace `except Exception` in `plan_generation.py:_analyze_requirements` (line 411) with specific exception types - [ ] Replace `except Exception` in `plan_generation.py:_generate_plan` (line 461) with specific exception types - [ ] Replace `except Exception` in `plan_generation.py:_validate` (line 562) with specific exception types - [ ] Replace `except Exception` in `plan_generation.py:_analyze_contexts` (line 621) with specific exception types - [ ] Remove `# pragma: no cover - defensive` comments where the new specific handlers are now testable - [ ] Run full nox suite and confirm all gates pass ## Definition of Done - [ ] All subtasks above are checked - [ ] All nine broad `except Exception` clauses replaced with specific handlers - [ ] TDD issue-capture scenarios exist and pass after the fix - [ ] Commit pushed to `fix/error-handling-agents-broad-except` with message: `fix(error-handling): replace broad except Exception clauses in agents module with specific handlers` - [ ] PR merged and linked to this issue - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.3.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 17:08:34 +00:00

#362 Epic: Security & Safety Hardening

freemo added this to the v3.7.0 milestone

2026-04-05 17:12:59 +00:00

freemo commented

2026-04-05 17:13:17 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Backlog (confirmed) — Code quality improvement. Broad except Exception clauses violate CONTRIBUTING.md standards but don't cause functional failures.
Milestone: v3.7.0 (assigned — code quality hardening)
Story Points: 5 (L) — 9 catch sites across 2 files, each requiring audit of legitimate exception types + TDD scenarios
MoSCoW: Could Have — Refactoring with no behavior change. Improves debuggability but doesn't add features or fix user-facing bugs.
Parent Epic: #362 (Security & Safety Hardening)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Backlog (confirmed) — Code quality improvement. Broad `except Exception` clauses violate CONTRIBUTING.md standards but don't cause functional failures. - **Milestone**: v3.7.0 (assigned — code quality hardening) - **Story Points**: 5 (L) — 9 catch sites across 2 files, each requiring audit of legitimate exception types + TDD scenarios - **MoSCoW**: Could Have — Refactoring with no behavior change. Improves debuggability but doesn't add features or fix user-facing bugs. - **Parent Epic**: #362 (Security & Safety Hardening) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 17:16:27 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 17:19:48 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo removed this from the v3.7.0 milestone

2026-04-06 23:49:07 +00:00