BUG-HUNT: [error-handling] Generic exception handling in `add` method #3253

New issue

Open

opened 2026-04-05 08:32:00 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 08:32:00 +00:00

Owner

Metadata

Branch: fix/error-handling/actor-registry-add-specific-exception
Commit Message: fix(actor): replace generic Exception catch in ActorRegistry.add with specific NotFoundError
Milestone: (unassigned — see backlog note)
Parent Epic: #362

Bug Report: [error-handling] — Generic exception handling in `add` method

Severity Assessment

Impact: The current implementation catches a generic Exception and then checks the exception message to determine if the actor already exists. This is not robust and could lead to incorrect behavior if the exception message changes or if another unexpected exception is caught.
Likelihood: High. This code will be executed every time a new actor is added.
Priority: Medium

Location

File: src/cleveragents/actor/registry.py
Function/Class: ActorRegistry.add
Lines: 226-236

Description

The add method in ActorRegistry uses a try...except Exception block to check if an actor already exists. It then checks the string representation of the exception to see if it contains the substring "already exists". This is a fragile way to handle errors and can lead to bugs. For example, if the underlying _actor_service.get_actor method raises a different exception with a message containing "already exists", it will be incorrectly treated as a duplicate actor error.

Evidence

        # Check for existing actor when not updating
        if not update:
            try:
                self._actor_service.get_actor(name)
                raise ValidationError(
                    f"Actor '{name}' already exists. Pass update=True to overwrite."
                )
            except Exception as exc:
                if "already exists" in str(exc):
                    raise
                # NotFoundError is expected for new actors

Expected Behavior

The code should catch a more specific exception, such as NotFoundError, to determine if the actor exists. If the actor exists, it should raise a specific ActorAlreadyExistsError exception.

Suggested Fix

Modify the _actor_service.get_actor method to raise a specific NotFoundError when the actor is not found. Then, in the add method, catch this specific exception. If the actor is found, raise a specific ActorAlreadyExistsError.

# In ActorService
class NotFoundError(Exception):
    pass

class ActorAlreadyExistsError(Exception):
    pass

# In ActorRegistry.add
        if not update:
            try:
                self._actor_service.get_actor(name)
                raise ActorAlreadyExistsError(f"Actor '{name}' already exists. Pass update=True to overwrite.")
            except NotFoundError:
                # This is the expected case for a new actor
                pass

Subtasks

Confirm ActorService.get_actor raises a specific NotFoundError (or equivalent) when actor is not found; add it if missing
Replace except Exception as exc in ActorRegistry.add with except NotFoundError
Introduce (or reuse) a typed ActorAlreadyExistsError exception and raise it in place of the generic ValidationError for duplicate-actor detection
Update all call sites and type annotations to reflect the new exception types
Add/update Behave unit test scenarios covering: new actor (NotFoundError path), duplicate actor (ActorAlreadyExistsError path), and unexpected exception propagation
Ensure nox -e typecheck passes with no # type: ignore suppressions

Definition of Done

ActorRegistry.add catches only NotFoundError (or the project-standard equivalent) instead of bare Exception
A typed ActorAlreadyExistsError is raised for duplicate-actor detection — no string-matching on exception messages
All existing and new Behave scenarios pass (nox -e unit_tests)
No regressions in integration tests (nox -e integration_tests)
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.8.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/actor-registry-add-specific-exception` - **Commit Message**: `fix(actor): replace generic Exception catch in ActorRegistry.add with specific NotFoundError` - **Milestone**: *(unassigned — see backlog note)* - **Parent Epic**: #362 ## Bug Report: [error-handling] — Generic exception handling in `add` method ### Severity Assessment - **Impact**: The current implementation catches a generic `Exception` and then checks the exception message to determine if the actor already exists. This is not robust and could lead to incorrect behavior if the exception message changes or if another unexpected exception is caught. - **Likelihood**: High. This code will be executed every time a new actor is added. - **Priority**: Medium ### Location - **File**: `src/cleveragents/actor/registry.py` - **Function/Class**: `ActorRegistry.add` - **Lines**: 226-236 ### Description The `add` method in `ActorRegistry` uses a `try...except Exception` block to check if an actor already exists. It then checks the string representation of the exception to see if it contains the substring "already exists". This is a fragile way to handle errors and can lead to bugs. For example, if the underlying `_actor_service.get_actor` method raises a different exception with a message containing "already exists", it will be incorrectly treated as a duplicate actor error. ### Evidence ```python # Check for existing actor when not updating if not update: try: self._actor_service.get_actor(name) raise ValidationError( f"Actor '{name}' already exists. Pass update=True to overwrite." ) except Exception as exc: if "already exists" in str(exc): raise # NotFoundError is expected for new actors ``` ### Expected Behavior The code should catch a more specific exception, such as `NotFoundError`, to determine if the actor exists. If the actor exists, it should raise a specific `ActorAlreadyExistsError` exception. ### Suggested Fix Modify the `_actor_service.get_actor` method to raise a specific `NotFoundError` when the actor is not found. Then, in the `add` method, catch this specific exception. If the actor is found, raise a specific `ActorAlreadyExistsError`. ```python # In ActorService class NotFoundError(Exception): pass class ActorAlreadyExistsError(Exception): pass # In ActorRegistry.add if not update: try: self._actor_service.get_actor(name) raise ActorAlreadyExistsError(f"Actor '{name}' already exists. Pass update=True to overwrite.") except NotFoundError: # This is the expected case for a new actor pass ``` ### Category error-handling ## Subtasks - [ ] Confirm `ActorService.get_actor` raises a specific `NotFoundError` (or equivalent) when actor is not found; add it if missing - [ ] Replace `except Exception as exc` in `ActorRegistry.add` with `except NotFoundError` - [ ] Introduce (or reuse) a typed `ActorAlreadyExistsError` exception and raise it in place of the generic `ValidationError` for duplicate-actor detection - [ ] Update all call sites and type annotations to reflect the new exception types - [ ] Add/update Behave unit test scenarios covering: new actor (NotFoundError path), duplicate actor (ActorAlreadyExistsError path), and unexpected exception propagation - [ ] Ensure `nox -e typecheck` passes with no `# type: ignore` suppressions ## Definition of Done - [ ] `ActorRegistry.add` catches only `NotFoundError` (or the project-standard equivalent) instead of bare `Exception` - [ ] A typed `ActorAlreadyExistsError` is raised for duplicate-actor detection — no string-matching on exception messages - [ ] All existing and new Behave scenarios pass (`nox -e unit_tests`) - [ ] No regressions in integration tests (`nox -e integration_tests`) - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.8.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 08:39:35 +00:00

#362 Epic: Security & Safety Hardening

freemo added this to the v3.7.0 milestone

2026-04-05 08:47:16 +00:00

freemo referenced this issue

2026-04-05 08:49:48 +00:00

[CA-AUTO] Project Owner — project-owner-1 — Session Tracker #2793

freemo referenced this issue

2026-04-05 09:11:44 +00:00

[CA-AUTO] Backlog Groomer — Session Tracker — groomer-1 — 2026-04-05 #3182

freemo added the