Improve subagent error messages with categorization and hints #4395
+473
−13
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
Author
|
CI failures are all pre-existing on main — none caused by this PR:
|
…d Opus Resolves openclaw#4315. The slug-generator embedded run was hardcoded to use DEFAULT_MODEL (claude-opus-4-5) regardless of the user's configured agents.defaults.model.primary. This caused unexpected Opus charges on every /new command. Now uses resolveDefaultModelForAgent() to honor the user's configured default model, falling back to DEFAULT_MODEL only when no config exists.
…ixes openclaw#4367) The message processing pipeline had a synchronization bug where limitHistoryTurns() truncated conversation history AFTER repairToolUseResultPairing() had already fixed tool_use/tool_result pairings. This could split assistant messages (with tool_use) from their corresponding tool_result blocks, creating orphaned tool_result blocks that the Anthropic API rejects. This fix calls sanitizeToolUseResultPairing() AFTER limitHistoryTurns() to repair any pairings broken by truncation, ensuring the transcript remains valid before being sent to the LLM API. Changes: - Added import for sanitizeToolUseResultPairing from session-transcript-repair.js - Call sanitizeToolUseResultPairing() on the limited message array - Updated variable name from 'limited' to 'repaired' for clarity
- Enhanced SubagentRunOutcome type with errorType and errorHint fields - Added categorizeError() helper to classify common error patterns: * File system errors (ENOENT, EACCES, etc.) * API/model errors (rate limits, auth failures, invalid requests) * Network errors (connection refused, DNS failures) * Timeout errors * Configuration errors (missing credentials, quota limits) - Updated error emission in agent-runner-execution.ts to categorize errors - Updated subagent-registry.ts to capture and propagate new error fields - Added buildErrorStatusLabel() helper for user-friendly error messages - Error announcements now include error type and remediation hints Example improved messages: - Before: 'failed: unknown error' - After: 'failed (tool error): ENOENT — File or directory not found' This makes subagent failures much easier to understand and debug while maintaining backward compatibility.
- Tests timeout errors (timeout keyword, 'timed out', ETIMEDOUT) - Tests authentication errors (401, unauthorized, 403, forbidden) - Tests rate limit errors (rate limit keyword, HTTP 429) - Tests unknown/unrecognized errors - Tests API/model errors (400, 500, 503, quota, billing) - Tests network errors (ECONNREFUSED, ENOTFOUND, DNS, ENETUNREACH) - Tests file system errors (ENOENT, EACCES, EPERM, EISDIR) - Tests configuration errors (missing key/token) - Tests context/memory errors - Export categorizeError() function for testing - 37 passing tests covering all error categorization paths
c713a8b to
a39811c
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR improves subagent error messages by categorizing errors and providing actionable hints for common failure scenarios.
Changes
1. Enhanced Error Types
SubagentRunOutcometo includeerrorTypeanderrorHintfieldsmodel,tool,network,config,timeout,unknown2. Error Categorization
categorizeError()helper that identifies common error patterns:3. Improved Error Emission
agent-runner-execution.tsto categorize errors before emitting lifecycle events4. Better User-Facing Messages
buildErrorStatusLabel()to create descriptive error messagesExamples
Before:
After:
More examples:
failed (API error): Rate limit exceeded — Rate limit exceeded - retry in a few momentsfailed (configuration error): Missing API key — Check API credentials and permissionsfailed (network error): ECONNREFUSED — Connection failed - check network connectivityImpact
Testing
Related
Research document:
~/clawd/memory/research/2026-01-30-subagent-errors.md