claude-code - 💡(How to fix) Fix [BUG] otelHeadersHelper blocks TUI when script is slow to return [1 participants]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

When otelHeadersHelper is configured and the helper script takes more than a few hundred milliseconds to return (e.g., due to a slow or unreachable token endpoint), the entire Claude Code TUI freezes — no input, no rendering — until the script completes or times out.

During the freeze, the terminal tab title changes to show the command being run (e.g., "curl"), confirming it executes synchronously in the foreground of the main process.

The otelHeadersHelper is invoked by the OTEL SDK's headers() function on every metric/log/trace export. With OTEL_METRIC_EXPORT_INTERVAL=60000 (60s) and only metrics enabled, this causes a 5-10 second freeze every 60 seconds. With logs and traces also enabled, the frequency increases significantly.

This affected multiple users across our organization (~thousands of engineers) after deploying otelHeadersHelper org-wide via managed settings.

What Should Happen?

otelHeadersHelper should run asynchronously so that a slow or failing helper does not block user interaction. If the helper is slow or fails, telemetry export should degrade gracefully (skip the export or use stale/cached headers) rather than freezing the UI.

Error Messages/Logs

No error messages — the TUI simply becomes unresponsive for the duration of the helper script execution.

Diagnostic output from monitoring curl processes during freezes:

# Ran: while true; do ps -eo pid,ppid,command | grep '[c]url' >> /tmp/curl_watch.log; sleep 0.5; done
# Result: curl hitting the /token endpoint with 10s timeout, same PID caught repeatedly over multiple seconds

Steps to Reproduce

1. Create a slow helper script:

   cat > /tmp/slow-otel-helper.sh << 'EOF'
   #!/bin/bash
   sleep 8
   echo '{"Authorization": "Bearer test"}'
   EOF
   chmod +x /tmp/slow-otel-helper.sh

2. Configure Claude Code settings (in settings.local.json or via managed settings):

   {
     "otelHeadersHelper": "/tmp/slow-otel-helper.sh",
     "env": {
       "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
       "OTEL_METRICS_EXPORTER": "otlp",
       "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
       "OTEL_EXPORTER_OTLP_ENDPOINT": "https://localhost:4318",
       "OTEL_METRIC_EXPORT_INTERVAL": "60000"
     }
   }

3. Launch claude in a terminal

4. Observe periodic TUI freezes (~8 seconds each) coinciding with the helper script execution. The terminal tab title changes to "sleep" during the freeze.

Workaround

We implemented a background-refresh pattern in the helper script: the script caches the JWT to disk, always returns immediately from the cache (or {} on first run), and refreshes the token in a detached background process. This ensures otelHeadersHelper never blocks regardless of endpoint latency.

Claude Model

Not applicable

Is this a regression?

I don't know

Claude Code Version

2.1.108

Platform

macOS

Operating System

macOS 15

Terminal/Shell

Terminal.app, iTerm2, VS Code integrated terminal, GoLand terminal