BUG-HUNT: [error-handling] Broad exception in _handle_file_search #1813

New issue

Open

opened 2026-04-02 23:55:09 +00:00 by freemo · 1 comment

freemo commented

2026-04-02 23:55:09 +00:00

Owner

Metadata

Branch: fix/error-handling-file-tools-handle-file-search
Commit Message: fix(tools): replace broad OSError catch with specific exception handling in _handle_file_search
Milestone: v3.7.0
Parent Epic: #1669

Background and Context

The _handle_file_search function in src/cleveragents/tool/builtins/file_tools.py uses a broad except (OSError, UnicodeDecodeError): block. Per the project's error-handling standards (CONTRIBUTING.md), exceptions should propagate to the top level where they can be properly logged and handled. Catch-all handlers without re-raising suppress errors, making debugging difficult and violating the fail-fast principle.

While UnicodeDecodeError is a valid concern when reading text files, catching all OSError exceptions can hide other issues like file not found, permission errors, or other I/O problems that are not related to decoding.

Current Behavior

The _handle_file_search function in src/cleveragents/tool/builtins/file_tools.py (lines 202–204) catches both OSError and UnicodeDecodeError broadly and silently continues:

        try:
            content = file_path.read_text(errors="replace")
        except (OSError, UnicodeDecodeError):
            continue

This can swallow any OSError — including permission errors, file-not-found errors, and other I/O problems unrelated to text decoding — and silently skip the file without any indication of what went wrong. The full traceback is lost, making debugging very difficult.

Expected Behavior

UnicodeDecodeError is caught and handled (skip the file), as it is an expected condition when reading arbitrary text files.
Unexpected OSError subtypes (e.g., PermissionError, FileNotFoundError) are either re-raised or explicitly handled with logging, rather than silently swallowed.
The fail-fast principle is respected: unexpected errors surface rather than being hidden.

Suggested Fix

Catch UnicodeDecodeError specifically. If other OSError exceptions are expected, catch them explicitly with appropriate handling:

        try:
            content = file_path.read_text(errors="replace")
        except UnicodeDecodeError:
            continue
        except OSError as e:
            # Log the error or handle specific OSError subtypes explicitly
            # e.g., if e.errno == errno.EACCES: continue  # permission error
            raise  # or handle explicitly

Acceptance Criteria

The _handle_file_search function no longer uses a broad except (OSError, UnicodeDecodeError): catch-all.
UnicodeDecodeError is caught and handled (file is skipped) as before.
Unexpected OSError subtypes are either re-raised or explicitly handled with appropriate logging.
All existing tests pass.
New BDD scenarios cover the specific exception handling paths.

Supporting Information

File: src/cleveragents/tool/builtins/file_tools.py
Function: _handle_file_search
Lines: 202–204
Severity: Low — potential to swallow and hide bugs, making debugging difficult
Related issues: #1761 (Broad exception in LangChainChatProvider.generate_changes), #1772 (A2aEventQueue swallows exceptions), #1774 (Silent failure in template rendering)

Subtasks

Investigate all OSError subtypes that may realistically occur in _handle_file_search and determine which should be silently skipped vs. propagated
Replace broad except (OSError, UnicodeDecodeError): with specific exception handling
Add logging for any OSError that is caught and suppressed (if applicable)
Tests (Behave): Add BDD scenarios for UnicodeDecodeError handling (file skipped)
Tests (Behave): Add BDD scenarios for unexpected OSError propagation
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-file-tools-handle-file-search` - **Commit Message**: `fix(tools): replace broad OSError catch with specific exception handling in _handle_file_search` - **Milestone**: v3.7.0 - **Parent Epic**: #1669 ## Background and Context The `_handle_file_search` function in `src/cleveragents/tool/builtins/file_tools.py` uses a broad `except (OSError, UnicodeDecodeError):` block. Per the project's error-handling standards (CONTRIBUTING.md), exceptions should propagate to the top level where they can be properly logged and handled. Catch-all handlers without re-raising suppress errors, making debugging difficult and violating the fail-fast principle. While `UnicodeDecodeError` is a valid concern when reading text files, catching all `OSError` exceptions can hide other issues like file not found, permission errors, or other I/O problems that are not related to decoding. ## Current Behavior The `_handle_file_search` function in `src/cleveragents/tool/builtins/file_tools.py` (lines 202–204) catches both `OSError` and `UnicodeDecodeError` broadly and silently continues: ```python try: content = file_path.read_text(errors="replace") except (OSError, UnicodeDecodeError): continue ``` This can swallow any `OSError` — including permission errors, file-not-found errors, and other I/O problems unrelated to text decoding — and silently skip the file without any indication of what went wrong. The full traceback is lost, making debugging very difficult. ## Expected Behavior - `UnicodeDecodeError` is caught and handled (skip the file), as it is an expected condition when reading arbitrary text files. - Unexpected `OSError` subtypes (e.g., `PermissionError`, `FileNotFoundError`) are either re-raised or explicitly handled with logging, rather than silently swallowed. - The fail-fast principle is respected: unexpected errors surface rather than being hidden. ## Suggested Fix Catch `UnicodeDecodeError` specifically. If other `OSError` exceptions are expected, catch them explicitly with appropriate handling: ```python try: content = file_path.read_text(errors="replace") except UnicodeDecodeError: continue except OSError as e: # Log the error or handle specific OSError subtypes explicitly # e.g., if e.errno == errno.EACCES: continue # permission error raise # or handle explicitly ``` ## Acceptance Criteria - The `_handle_file_search` function no longer uses a broad `except (OSError, UnicodeDecodeError):` catch-all. - `UnicodeDecodeError` is caught and handled (file is skipped) as before. - Unexpected `OSError` subtypes are either re-raised or explicitly handled with appropriate logging. - All existing tests pass. - New BDD scenarios cover the specific exception handling paths. ## Supporting Information - **File**: `src/cleveragents/tool/builtins/file_tools.py` - **Function**: `_handle_file_search` - **Lines**: 202–204 - **Severity**: Low — potential to swallow and hide bugs, making debugging difficult - **Related issues**: #1761 (Broad exception in LangChainChatProvider.generate_changes), #1772 (A2aEventQueue swallows exceptions), #1774 (Silent failure in template rendering) ## Subtasks - [ ] Investigate all `OSError` subtypes that may realistically occur in `_handle_file_search` and determine which should be silently skipped vs. propagated - [ ] Replace broad `except (OSError, UnicodeDecodeError):` with specific exception handling - [ ] Add logging for any `OSError` that is caught and suppressed (if applicable) - [ ] Tests (Behave): Add BDD scenarios for `UnicodeDecodeError` handling (file skipped) - [ ] Tests (Behave): Add BDD scenarios for unexpected `OSError` propagation - [ ] 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.7.0 milestone

2026-04-02 23:56:02 +00:00

freemo commented

2026-04-02 23:57:37 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Should Have — bug or spec compliance issue.

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

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

freemo added a new dependency

2026-04-02 23:58:24 +00:00

#1669 Bug Hunting Session