UAT: agents config set/get with invalid key or value shows cryptic "INTERNAL" error instead of user-friendly message #1995

Open
opened 2026-04-03 00:32:45 +00:00 by freemo · 3 comments
Owner

Metadata

  • Branch: fix/config-set-get-bad-parameter-user-friendly-error
  • Commit Message: fix(cli): propagate BadParameter and TypeError from config set/get as user-friendly errors instead of INTERNAL
  • Milestone: v3.7.0
  • Parent Epic: #936

Bug Report

Feature Area: CLI config commands (get/set/list configuration)

Severity: High

Parent Epic: #936 (Output Rendering Pipeline Integration)

Summary

When agents config set or agents config get is called with an invalid key or an invalid value type, the error is wrapped as a generic "Error [500] INTERNAL: An unexpected error occurred" message instead of a clear, user-friendly error message.

Steps to Reproduce

agents config get nonexistent.key
# Expected: clear error message about unknown key
# Actual: "Error [500] INTERNAL: An unexpected error occurred"

agents config set plan.concurrency notanumber
# Expected: clear error message about type mismatch
# Actual: "Error [500] INTERNAL: An unexpected error occurred"

Actual Behavior

$ agents config get nonexistent.key
Wrapping unexpected exception: BadParameter: Unknown configuration key: 'nonexistent.key' (normalized: 'nonexistent.key'). Valid keys include: actor.default.estimation, actor.default.execution, ...
Error [500] INTERNAL: An unexpected error occurred
$ agents config set plan.concurrency notanumber
Wrapping unexpected exception: TypeError: Type mismatch for key 'plan.concurrency': expected int, got str with value 'notanumber'.
Error [500] INTERNAL: An unexpected error occurred

Expected Behavior

When an invalid key is provided, the command should show a clear error message like:

Error: Invalid value for 'KEY': Unknown configuration key: 'nonexistent.key'. Valid keys include: ...

and exit with a non-zero exit code (exit code 2 for usage errors).

When an invalid value type is provided (e.g., a string for an integer key), the command should show a clear type mismatch error:

Error: Invalid value for 'VALUE': Type mismatch for key 'plan.concurrency': expected int, got str with value 'notanumber'.

Root Cause Analysis

The _validate_key() function in src/cleveragents/cli/commands/config.py raises typer.BadParameter, but this exception is being caught by a higher-level error handler in src/cleveragents/cli/main.py that wraps it as an INTERNAL error via wrap_unexpected() instead of letting Typer handle it gracefully.

Similarly, TypeError raised during type validation in the config set/get path is not being caught and converted to a user-friendly error — it propagates to the same generic handler.

The BadParameter exception from Typer is designed to produce a clean error message like "Error: Invalid value for 'KEY': ..." but the current error handling pipeline in main() intercepts it before Typer can process it.

Affected files:

  • src/cleveragents/cli/commands/config.py_validate_key() raises typer.BadParameter; type validation raises TypeError
  • src/cleveragents/cli/main.pymain() function's exception handler wraps BadParameter and TypeError as unexpected

Impact

Users get confusing, cryptic error messages when they make simple mistakes like typos in key names or providing wrong value types. This is a poor user experience for a common error scenario.

Subtasks

  • Identify all locations in src/cleveragents/cli/commands/config.py where typer.BadParameter and TypeError are raised for invalid key/value inputs
  • Update the exception handler in src/cleveragents/cli/main.py to re-raise or exclude typer.BadParameter and TypeError (from config validation) before the generic wrap_unexpected catch — consistent with the fix pattern established in #1971
  • Verify _validate_key() in src/cleveragents/cli/commands/config.py raises typer.BadParameter correctly (no change expected, but confirm)
  • Ensure TypeError from type validation is caught at the command level and re-raised as typer.BadParameter with a user-friendly message
  • Tests (Behave): Add/verify BDD scenarios for agents config get <invalid-key> and agents config set <key> <invalid-value> producing user-friendly error messages with correct exit codes
  • Verify coverage >= 97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

  • agents config get nonexistent.key exits with code 2 and outputs a clear error message identifying the unknown key
  • agents config set plan.concurrency notanumber exits with code 2 and outputs a clear type mismatch error message
  • typer.BadParameter raised in _validate_key() is NOT caught by the generic wrap_unexpected handler in main()
  • TypeError from type validation is converted to a user-friendly typer.BadParameter before reaching main()'s generic handler
  • Other valid agents config get/set invocations continue to work correctly
  • 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: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/config-set-get-bad-parameter-user-friendly-error` - **Commit Message**: `fix(cli): propagate BadParameter and TypeError from config set/get as user-friendly errors instead of INTERNAL` - **Milestone**: v3.7.0 - **Parent Epic**: #936 ## Bug Report **Feature Area:** CLI config commands (get/set/list configuration) **Severity:** High **Parent Epic:** #936 (Output Rendering Pipeline Integration) ### Summary When `agents config set` or `agents config get` is called with an invalid key or an invalid value type, the error is wrapped as a generic `"Error [500] INTERNAL: An unexpected error occurred"` message instead of a clear, user-friendly error message. ### Steps to Reproduce ```bash agents config get nonexistent.key # Expected: clear error message about unknown key # Actual: "Error [500] INTERNAL: An unexpected error occurred" agents config set plan.concurrency notanumber # Expected: clear error message about type mismatch # Actual: "Error [500] INTERNAL: An unexpected error occurred" ``` ### Actual Behavior ``` $ agents config get nonexistent.key Wrapping unexpected exception: BadParameter: Unknown configuration key: 'nonexistent.key' (normalized: 'nonexistent.key'). Valid keys include: actor.default.estimation, actor.default.execution, ... Error [500] INTERNAL: An unexpected error occurred ``` ``` $ agents config set plan.concurrency notanumber Wrapping unexpected exception: TypeError: Type mismatch for key 'plan.concurrency': expected int, got str with value 'notanumber'. Error [500] INTERNAL: An unexpected error occurred ``` ### Expected Behavior When an invalid key is provided, the command should show a clear error message like: ``` Error: Invalid value for 'KEY': Unknown configuration key: 'nonexistent.key'. Valid keys include: ... ``` and exit with a non-zero exit code (exit code 2 for usage errors). When an invalid value type is provided (e.g., a string for an integer key), the command should show a clear type mismatch error: ``` Error: Invalid value for 'VALUE': Type mismatch for key 'plan.concurrency': expected int, got str with value 'notanumber'. ``` ### Root Cause Analysis The `_validate_key()` function in `src/cleveragents/cli/commands/config.py` raises `typer.BadParameter`, but this exception is being caught by a higher-level error handler in `src/cleveragents/cli/main.py` that wraps it as an INTERNAL error via `wrap_unexpected()` instead of letting Typer handle it gracefully. Similarly, `TypeError` raised during type validation in the config set/get path is not being caught and converted to a user-friendly error — it propagates to the same generic handler. The `BadParameter` exception from Typer is designed to produce a clean error message like `"Error: Invalid value for 'KEY': ..."` but the current error handling pipeline in `main()` intercepts it before Typer can process it. **Affected files:** - `src/cleveragents/cli/commands/config.py` — `_validate_key()` raises `typer.BadParameter`; type validation raises `TypeError` - `src/cleveragents/cli/main.py` — `main()` function's exception handler wraps `BadParameter` and `TypeError` as unexpected ### Impact Users get confusing, cryptic error messages when they make simple mistakes like typos in key names or providing wrong value types. This is a poor user experience for a common error scenario. ## Subtasks - [ ] Identify all locations in `src/cleveragents/cli/commands/config.py` where `typer.BadParameter` and `TypeError` are raised for invalid key/value inputs - [ ] Update the exception handler in `src/cleveragents/cli/main.py` to re-raise or exclude `typer.BadParameter` and `TypeError` (from config validation) before the generic `wrap_unexpected` catch — consistent with the fix pattern established in #1971 - [ ] Verify `_validate_key()` in `src/cleveragents/cli/commands/config.py` raises `typer.BadParameter` correctly (no change expected, but confirm) - [ ] Ensure `TypeError` from type validation is caught at the command level and re-raised as `typer.BadParameter` with a user-friendly message - [ ] Tests (Behave): Add/verify BDD scenarios for `agents config get <invalid-key>` and `agents config set <key> <invalid-value>` producing user-friendly error messages with correct exit codes - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done - [ ] `agents config get nonexistent.key` exits with code 2 and outputs a clear error message identifying the unknown key - [ ] `agents config set plan.concurrency notanumber` exits with code 2 and outputs a clear type mismatch error message - [ ] `typer.BadParameter` raised in `_validate_key()` is NOT caught by the generic `wrap_unexpected` handler in `main()` - [ ] `TypeError` from type validation is converted to a user-friendly `typer.BadParameter` before reaching `main()`'s generic handler - [ ] Other valid `agents config get/set` invocations continue to work correctly - [ ] 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: UAT Testing | Agent: ca-uat-tester
freemo added this to the v3.7.0 milestone 2026-04-03 00:33:25 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: High — User-facing error messages showing "INTERNAL" for common input mistakes is a significant UX degradation. The root cause is well-identified (exception handler in main.py wrapping BadParameter and TypeError).
  • Milestone: v3.7.0 (TUI Implementation — already assigned, confirmed correct since this is part of the Output Rendering Pipeline Epic #936)
  • MoSCoW: Should Have — While not a spec-mandated behavioral requirement, user-friendly error messages are critical for CLI usability. The spec's error handling model expects clean error propagation, and this violates that intent. However, the core functionality works; only the error presentation is affected.
  • Parent Epic: #936 (Output Rendering Pipeline Integration — already linked, confirmed correct)

Well-documented issue with clear root cause analysis, reproduction steps, and a fix pattern already established in #1971.


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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — User-facing error messages showing "INTERNAL" for common input mistakes is a significant UX degradation. The root cause is well-identified (exception handler in `main.py` wrapping `BadParameter` and `TypeError`). - **Milestone**: v3.7.0 (TUI Implementation — already assigned, confirmed correct since this is part of the Output Rendering Pipeline Epic #936) - **MoSCoW**: Should Have — While not a spec-mandated behavioral requirement, user-friendly error messages are critical for CLI usability. The spec's error handling model expects clean error propagation, and this violates that intent. However, the core functionality works; only the error presentation is affected. - **Parent Epic**: #936 (Output Rendering Pipeline Integration — already linked, confirmed correct) Well-documented issue with clear root cause analysis, reproduction steps, and a fix pattern already established in #1971. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: High — already correctly labeled
  • Milestone: v3.7.0
  • MoSCoW: Should Have — already correctly labeled; user-facing error messages should be clear and actionable per spec
  • Parent Epic: #868 (TUI Interface, Modals and Persona System)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — already correctly labeled - **Milestone**: v3.7.0 - **MoSCoW**: Should Have — already correctly labeled; user-facing error messages should be clear and actionable per spec - **Parent Epic**: #868 (TUI Interface, Modals and Persona System) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: High (unchanged)
  • Milestone: v3.7.0 (already assigned)
  • MoSCoW: Should Have (org-level label already present) — Cryptic "INTERNAL" error messages for invalid config keys/values degrade the user experience. The specification requires user-friendly error messages for CLI operations.

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

Issue triaged by project owner: - **State**: Verified ✅ - **Priority**: High (unchanged) - **Milestone**: v3.7.0 (already assigned) - **MoSCoW**: Should Have (org-level label already present) — Cryptic "INTERNAL" error messages for invalid config keys/values degrade the user experience. The specification requires user-friendly error messages for CLI operations. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
freemo removed this from the v3.7.0 milestone 2026-04-06 20:58:20 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#1995
No description provided.