cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [Error Handling] Broad exception handling in TUI command router #1866

New issue

Open

opened 2026-04-03 00:01:44 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 00:01:44 +00:00

Owner

Metadata

Branch: fix/error-handling-tui-command-router
Commit Message: fix(tui): replace broad exception handlers with specific exceptions in TuiCommandRouter
Milestone: v3.6.0
Parent Epic: ⚠️ No open parent Epic found for v3.6.0 — requires manual linking by a maintainer.

Background and Context

The TuiCommandRouter class in src/cleveragents/tui/commands.py uses overly broad except Exception blocks in its _session_export and _session_import methods. Per the project's error-handling standards (CONTRIBUTING.md — Exception Propagation and Fail-Fast Principles), exceptions must not be suppressed and should only be caught when they can be meaningfully handled. Broad catch-all handlers hide the root cause of bugs, swallow important exceptions (e.g., FileNotFoundError, json.JSONDecodeError, PermissionError), and make debugging significantly harder.

Current Behavior

The following methods use except Exception as exc: as a catch-all:

src/cleveragents/tui/commands.py:
- TuiCommandRouter._session_export (line 171)
- TuiCommandRouter._session_import (line 185)

Example:

def _session_export(self, tokens: list[str], *, session_id: str) -> str:
    ...
    except Exception as exc:
        return f"Export failed: {exc}"

def _session_import(self, tokens: list[str]) -> str:
    ...
    except Exception as exc:
        return f"Import failed: {exc}"

Expected Behavior

Each except clause should catch only the specific exception types that can realistically occur and be meaningfully handled at that point:

File I/O operations → catch FileNotFoundError, PermissionError, OSError
JSON serialisation/deserialisation → catch json.JSONDecodeError, ValueError
Any remaining truly unexpected exceptions should be allowed to propagate naturally to the top-level handler

Acceptance Criteria

All except Exception catch-all handlers in _session_export and _session_import are replaced with specific exception types
No exceptions are silently swallowed — any caught exception is either meaningfully handled (retry, cleanup, context enrichment) or re-raised
All existing tests continue to pass
New BDD scenarios cover the specific exception paths

Supporting Information

Bug reported by: ca-bug-hunter (Bug Hunting supervisor)
Related issue: #1824 (similar error-handling review for agent graphs)
CONTRIBUTING.md — Exception Propagation: "Do not use bare catch-all exception handlers without re-raising unless you have specific recovery logic."
CONTRIBUTING.md — Fail-Fast Principles: "No Silent Failures — Avoid returning null or default values when an error condition exists — raise exceptions or return explicit error types."

Subtasks

Audit _session_export in commands.py — identify what exceptions can realistically be raised (file I/O, JSON serialisation)
Audit _session_import in commands.py — identify what exceptions can realistically be raised (file I/O, JSON deserialisation, schema validation)
Replace each except Exception: with the narrowest applicable specific exception type(s)
Ensure any caught exception is either meaningfully handled or re-raised; remove silent swallowing
Tests (Behave): Add scenarios covering specific exception paths (e.g., file not found, JSON parse error) for affected methods
Tests (Behave): Add scenarios verifying that unexpected exceptions propagate correctly (are not swallowed)
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
All except Exception: catch-all handlers in _session_export and _session_import have been replaced with specific exception types.
No exceptions are silently swallowed in the affected functions.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, 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.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/error-handling-tui-command-router` - **Commit Message**: `fix(tui): replace broad exception handlers with specific exceptions in TuiCommandRouter` - **Milestone**: v3.6.0 - **Parent Epic**: ⚠️ *No open parent Epic found for v3.6.0 — requires manual linking by a maintainer.* ## Background and Context The `TuiCommandRouter` class in `src/cleveragents/tui/commands.py` uses overly broad `except Exception` blocks in its `_session_export` and `_session_import` methods. Per the project's error-handling standards (CONTRIBUTING.md — *Exception Propagation* and *Fail-Fast Principles*), exceptions must not be suppressed and should only be caught when they can be meaningfully handled. Broad catch-all handlers hide the root cause of bugs, swallow important exceptions (e.g., `FileNotFoundError`, `json.JSONDecodeError`, `PermissionError`), and make debugging significantly harder. ## Current Behavior The following methods use `except Exception as exc:` as a catch-all: - `src/cleveragents/tui/commands.py`: - `TuiCommandRouter._session_export` (line 171) - `TuiCommandRouter._session_import` (line 185) Example: ```python def _session_export(self, tokens: list[str], *, session_id: str) -> str: ... except Exception as exc: return f"Export failed: {exc}" def _session_import(self, tokens: list[str]) -> str: ... except Exception as exc: return f"Import failed: {exc}" ``` ## Expected Behavior Each `except` clause should catch only the specific exception types that can realistically occur and be meaningfully handled at that point: - File I/O operations → catch `FileNotFoundError`, `PermissionError`, `OSError` - JSON serialisation/deserialisation → catch `json.JSONDecodeError`, `ValueError` - Any remaining truly unexpected exceptions should be allowed to propagate naturally to the top-level handler ## Acceptance Criteria - [ ] All `except Exception` catch-all handlers in `_session_export` and `_session_import` are replaced with specific exception types - [ ] No exceptions are silently swallowed — any caught exception is either meaningfully handled (retry, cleanup, context enrichment) or re-raised - [ ] All existing tests continue to pass - [ ] New BDD scenarios cover the specific exception paths ## Supporting Information - Bug reported by: ca-bug-hunter (Bug Hunting supervisor) - Related issue: #1824 (similar error-handling review for agent graphs) - CONTRIBUTING.md — *Exception Propagation*: "Do not use bare catch-all exception handlers without re-raising unless you have specific recovery logic." - CONTRIBUTING.md — *Fail-Fast Principles*: "No Silent Failures — Avoid returning null or default values when an error condition exists — raise exceptions or return explicit error types." ## Subtasks - [ ] Audit `_session_export` in `commands.py` — identify what exceptions can realistically be raised (file I/O, JSON serialisation) - [ ] Audit `_session_import` in `commands.py` — identify what exceptions can realistically be raised (file I/O, JSON deserialisation, schema validation) - [ ] Replace each `except Exception:` with the narrowest applicable specific exception type(s) - [ ] Ensure any caught exception is either meaningfully handled or re-raised; remove silent swallowing - [ ] Tests (Behave): Add scenarios covering specific exception paths (e.g., file not found, JSON parse error) for affected methods - [ ] Tests (Behave): Add scenarios verifying that unexpected exceptions propagate correctly (are not swallowed) - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - All `except Exception:` catch-all handlers in `_session_export` and `_session_import` have been replaced with specific exception types. - No exceptions are silently swallowed in the affected functions. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, 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. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo added this to the v3.6.0 milestone

2026-04-03 00:02:39 +00:00

freemo commented

2026-04-03 00:03:29 +00:00

Author

Owner

⚠️ Orphan Issue — Manual Linking Required

This issue has no parent Epic dependency link. No open Type/Epic issue was found for milestone v3.6.0 at the time of creation.

A maintainer must manually link this issue to the appropriate parent Epic using Forgejo's dependency system (this issue should block the parent Epic).

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

⚠️ **Orphan Issue — Manual Linking Required** This issue has no parent Epic dependency link. No open `Type/Epic` issue was found for milestone `v3.6.0` at the time of creation. A maintainer must manually link this issue to the appropriate parent Epic using Forgejo's dependency system (this issue should **block** the parent Epic). --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo commented

2026-04-03 00:04:55 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Should Have — bug or error handling improvement.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: MoSCoW/Should Have — bug or error handling improvement. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added the

labels

2026-04-03 00:06:31 +00:00

freemo referenced this issue

2026-04-03 00:08:57 +00:00

[Automated] Backlog Groomer Session State — v3.7.0 #1463