BUG-HUNT: [error-handling] Inconsistent error handling in `_register_subcommands` #2394

New issue

Open

opened 2026-04-03 17:31:14 +00:00 by freemo · 1 comment

freemo commented

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

Owner

Metadata

Branch: fix/error-handling-register-subcommands
Commit Message: fix(cli): use wrap_unexpected and classify_error in _register_subcommands
Milestone: v3.6.0
Parent Epic: #400

Background and Context

The _register_subcommands function in src/cleveragents/cli/main.py uses a bare except Exception: block to catch errors during the import of subcommands. When an exception is caught, it is printed directly to the console along with a full traceback via traceback.format_exc(). This is inconsistent with the error handling strategy used elsewhere in the file, which utilises wrap_unexpected and classify_error to provide user-friendly, redacted error messages.

This is an error-handling category bug: the code bypasses the standard error handling and redaction mechanism, potentially leaking internal stack traces to the user.

Current Behavior

When an exception occurs during subcommand registration (e.g., an ImportError in a CLI command module), the raw exception and full stack trace are printed directly to the standard error console:

    except Exception as exc:  # pragma: no cover
        import traceback

        err = get_err_console()
        err.print(f"[red]Failed to register subcommands:[/red] {exc}")
        err.print(traceback.format_exc())
        return

Location: src/cleveragents/cli/main.py, function _register_subcommands, lines 104–110.

This violates the project's error handling conventions, which require exceptions to be wrapped via wrap_unexpected and classified via classify_error to ensure consistent, user-friendly, and redacted error output.

Expected Behavior

Exceptions during subcommand registration should be wrapped using wrap_unexpected and classified using classify_error to ensure that error messages are consistent, user-friendly, and do not leak internal implementation details:

    except Exception as exc:  # pragma: no cover
        from cleveragents.core.error_handling import classify_error, wrap_unexpected

        err = get_err_console()
        safe = wrap_unexpected(exc, safe_message="Failed to register subcommands")
        info = classify_error(safe)
        err.print(
            f"[red]Error [{info.code.value}] {info.code.name}:[/red] {info.message}"
        )
        return

Severity Assessment

Impact: Potential for leaking internal stack traces to the user, bypassing the standard error handling and redaction mechanism.
Likelihood: Low — requires an import error in the CLI commands, which is unlikely in a stable release.
Priority: Medium

Subtasks

Replace the bare except Exception block in _register_subcommands with wrap_unexpected + classify_error pattern
Remove the inline import traceback and direct traceback.format_exc() call
Tests (Behave): Add scenario covering the error path in _register_subcommands to verify the new error handling output
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.
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-register-subcommands` - **Commit Message**: `fix(cli): use wrap_unexpected and classify_error in _register_subcommands` - **Milestone**: v3.6.0 - **Parent Epic**: #400 ## Background and Context The `_register_subcommands` function in `src/cleveragents/cli/main.py` uses a bare `except Exception:` block to catch errors during the import of subcommands. When an exception is caught, it is printed directly to the console along with a full traceback via `traceback.format_exc()`. This is inconsistent with the error handling strategy used elsewhere in the file, which utilises `wrap_unexpected` and `classify_error` to provide user-friendly, redacted error messages. This is an **error-handling** category bug: the code bypasses the standard error handling and redaction mechanism, potentially leaking internal stack traces to the user. ## Current Behavior When an exception occurs during subcommand registration (e.g., an `ImportError` in a CLI command module), the raw exception and full stack trace are printed directly to the standard error console: ```python except Exception as exc: # pragma: no cover import traceback err = get_err_console() err.print(f"[red]Failed to register subcommands:[/red] {exc}") err.print(traceback.format_exc()) return ``` **Location**: `src/cleveragents/cli/main.py`, function `_register_subcommands`, lines 104–110. This violates the project's error handling conventions, which require exceptions to be wrapped via `wrap_unexpected` and classified via `classify_error` to ensure consistent, user-friendly, and redacted error output. ## Expected Behavior Exceptions during subcommand registration should be wrapped using `wrap_unexpected` and classified using `classify_error` to ensure that error messages are consistent, user-friendly, and do not leak internal implementation details: ```python except Exception as exc: # pragma: no cover from cleveragents.core.error_handling import classify_error, wrap_unexpected err = get_err_console() safe = wrap_unexpected(exc, safe_message="Failed to register subcommands") info = classify_error(safe) err.print( f"[red]Error [{info.code.value}] {info.code.name}:[/red] {info.message}" ) return ``` ## Severity Assessment - **Impact**: Potential for leaking internal stack traces to the user, bypassing the standard error handling and redaction mechanism. - **Likelihood**: Low — requires an import error in the CLI commands, which is unlikely in a stable release. - **Priority**: Medium ## Subtasks - [ ] Replace the bare `except Exception` block in `_register_subcommands` with `wrap_unexpected` + `classify_error` pattern - [ ] Remove the inline `import traceback` and direct `traceback.format_exc()` call - [ ] Tests (Behave): Add scenario covering the error path in `_register_subcommands` to verify the new error handling output - [ ] 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. - 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 17:31:30 +00:00

freemo added a new dependency

2026-04-03 17:32:17 +00:00

#400 Epic: Post-MVP Security

freemo commented

2026-04-03 18:25:04 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — Bare except Exception: in subcommand registration hides import errors. This is an error handling quality issue.
Milestone: v3.6.0
MoSCoW: Could Have — The error handling works (subcommands load), but the pattern is inconsistent with the project's error handling standards. Low risk of actual issues.
Parent Epic: #400 (Post-MVP Security)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — Bare `except Exception:` in subcommand registration hides import errors. This is an error handling quality issue. - **Milestone**: v3.6.0 - **MoSCoW**: Could Have — The error handling works (subcommands load), but the pattern is inconsistent with the project's error handling standards. Low risk of actual issues. - **Parent Epic**: #400 (Post-MVP Security) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added the

MoSCoW

Could have

label

2026-04-03 18:25:37 +00:00

freemo removed the

MoSCoW

Could have

label

2026-04-05 04:16:53 +00:00