fix(telemetry): skip signal handler registration in non-main threads

[giulio-leone]

Problem

When CrewAI is initialized from a non-main thread (e.g. Streamlit, Flask, Django, Jupyter notebooks), the telemetry module prints multiple noisy ValueError tracebacks:

Cannot register SIGTERM handler: not running in main thread
Traceback (most recent call last):
  File ".../crewai/telemetry/telemetry.py", line 214, in _register_signal_handler
    signal.signal(sig, handler)
ValueError: signal only works in main thread of the main interpreter

This is repeated for SIGTERM, SIGINT, SIGHUP, SIGTSTP, and SIGCONT — up to 5 tracebacks per initialization.

Root Cause

_register_shutdown_handlers() calls signal.signal() unconditionally. When running in a non-main thread, Python raises ValueError which is caught but logged with exc_info=e, printing the full traceback.

Fix

Check threading.current_thread() is not threading.main_thread() before attempting any signal registration. If not in the main thread, skip signal registration entirely with a logger.debug() message. The atexit handler still registers (it works from any thread).

Test

Added test_no_signal_handler_traceback_in_non_main_thread that verifies:

• No exceptions raised when initializing telemetry from a non-main thread
• No ValueError tracebacks in stderr output

Fixes #4289

---

Note

Low Risk
Low risk: adds a simple main-thread guard around signal.signal registration and a regression test; behavior change is limited to telemetry shutdown signal handling when initialized off the main thread.

Overview
Prevents noisy ValueError tracebacks when Telemetry is initialized from a non-main thread by skipping all signal handler registration in _register_shutdown_handlers unless running on the main thread (while still registering the atexit shutdown hook).

Adds a regression test that initializes Telemetry in a background thread and asserts signal.signal is never called and a debug log message is emitted.

^{Written by Cursor Bugbot for commit db07bfc. This will update automatically on new commits. Configure here.}

[giulio-leone]

Friendly ping — CI is green and this is ready for review. Happy to address any feedback. Thanks!

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Free Tier Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[Copilot]

Pull request overview

This PR fixes a noisy UX problem where CrewAI would print multiple ValueError tracebacks when telemetry was initialized from a non-main thread (e.g., Streamlit, Flask, Jupyter). The root cause was _register_shutdown_handlers() unconditionally calling signal.signal(), which Python only allows from the main thread.

Changes:

• Added a threading.current_thread() is not threading.main_thread() guard in _register_shutdown_handlers() to skip signal registration in non-main threads with a debug-level log, while still registering the atexit handler.
• Added a regression test test_no_signal_handler_traceback_in_non_main_thread to verify the fix.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
lib/crewai/src/crewai/telemetry/telemetry.py	Adds thread check before signal handler registration; returns early with a debug log if not on the main thread
lib/crewai/tests/telemetry/test_telemetry.py	Adds regression test verifying no exceptions and no signal.signal calls when telemetry is initialized from a non-main thread

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[giulio-leone]

Both review items addressed: comments removed, capsys replaced with mock signal.signal assertion. All 10 tests pass.

[giulio-leone]

All feedback from @greysonlalonde addressed: removed inline comments (debug log is sufficient), replaced capsys with signal.signal mock + threading.Event. All CI checks pass. Could you re-review?

[giulio-leone]

@greysonlalonde Both requested changes have been addressed:

1. Inline comments removed (commit 231f7c3) — only the debug log message remains
2. capsys replaced with mock (commit 9c0e79f) — test now mocks signal.signal and asserts it is never called from a non-main thread

All CI checks are passing ✅. Ready for re-review when convenient.

[greysonlalonde]

Thank you!