fix: append traceback to tool execution error messages

[jasoncobra3]

Closes #6262

Problem

When a tool raised an exception, CrewAI caught it and
returned a generic string like "Error executing tool: {e}",
discarding the original traceback. This made debugging
impossible — users couldn't tell if the failure was a
network error, validation error, rate limit, or tool bug.

Fix

Appended traceback.format_exc(limit=5) to all tool
execution error returns across 4 files:

• agents/crew_agent_executor.py — main tool execution handler
• experimental/agent_executor.py — 4 exception handlers
  including printer output and action.result
• utilities/agent_utils.py — native tool call handler
• llm.py — LLMCallFailedEvent and ToolUsageErrorEvent

Design Decisions

• "Error executing tool:" prefix preserved — avoids
  breaking existing parsing logic
• limit=5 chosen to balance debuggability vs LLM
  context window consumption
• Full exception type and message still visible at start
  of error string before the traceback

Testing

Pre-existing test failures (RuntimeError: Network is disabled) confirmed unrelated to this change via
git stash verification on Windows Python 3.13
with pytest-recording.

Summary by CodeRabbit

• Bug Fixes
  • Enhanced error diagnostics by including detailed stack traces in tool failure messages, enabling better troubleshooting and debugging when tools encounter errors.

[corridor-security]

Summary: This PR adds traceback details to tool execution error messages and related telemetry/error propagation paths.

Risk: Low risk. No exploitable security vulnerabilities were identified; the added tracebacks expose diagnostic context but do not create a realistic attacker-controlled privilege, data access, injection, or execution path in the reviewed changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 617f1ac3-8c66-41f6-bd95-eb1dee758868

📥 Commits

Reviewing files that changed from the base of the PR and between 9db2d44 and 8b75f33.

📒 Files selected for processing (4)

• lib/crewai/src/crewai/agents/crew_agent_executor.py
• lib/crewai/src/crewai/experimental/agent_executor.py
• lib/crewai/src/crewai/llm.py
• lib/crewai/src/crewai/utilities/agent_utils.py

---

📝 Walkthrough

Walkthrough

Four files import traceback and update every tool-failure exception handler to append traceback.format_exc(limit=5) to the error string returned to the agent or emitted in events, replacing the previous message-only strings. Changes span the legacy and native tool execution paths in both executor implementations, the shared utility helper, and the LLM layer.

Changes

Tool Exception Traceback Enrichment

Layer / File(s)	Summary
Agent executor and utility tool error paths lib/crewai/src/crewai/agents/crew_agent_executor.py, lib/crewai/src/crewai/utilities/agent_utils.py, lib/crewai/src/crewai/experimental/agent_executor.py	Adds traceback import to each file and updates exception handlers in _execute_single_native_tool_call (crew executor and agent utils), the legacy tool execution path, the native parallel batch path, and the experimental single native call path to include traceback.format_exc(limit=5) in the result string alongside the error message.
LLM-level tool call exception reporting lib/crewai/src/crewai/llm.py	Adds traceback import and extends _handle_tool_call's exception handler to include a truncated traceback in both the log output and the LLMCallFailedEvent.error payload.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	The PR partially addresses issue #6262 by including traceback information in error messages, but does not implement the structured error format (with type, message, retryable fields) proposed in the linked issue.	Clarify whether the approach of appending traceback strings satisfies the requirement for structured error objects with type and message fields, or if additional refactoring is needed.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: appending traceback information to tool execution error messages across multiple files.
Out of Scope Changes check	✅ Passed	All changes are focused on appending traceback information to tool execution error handling across the four specified files, with no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[jasoncobra3]

Hi! Addressing the CodeRabbit inconclusive check.

We intentionally chose appending traceback strings
over the structured JSON format proposed in the issue
for these reasons:

1. No breaking changes — the "Error executing tool:"
   prefix is preserved, existing parsing logic is unaffected
2. LLM readability — plain text tracebacks are more
   naturally readable by the LLM agent than JSON error objects
3. Minimal scope — structured error objects would require
   changes to how agents parse tool responses, which is a
   larger refactor beyond this bug fix

This PR addresses the core debuggability problem from #6262
(root cause is no longer discarded). The structured error
format could be a separate follow-up enhancement.

Happy to add the structured format if maintainers prefer that
approach — just let me know!