Troubleshooting Guide

Script Permission Denied

Solution: Make the script executable:

chmod +x create_cc_alias.sh
./create_cc_alias.sh

Claude Binary Not Found

Solution: Install Claude Code CLI first:

1. Visit Claude Code installation guide
2. Follow the installation instructions for your system
3. Verify installation: claude --version
4. Run the CC alias installer again

Node.js Version Too Old

Solution: Upgrade Node.js to version 22 or higher:

# Using Homebrew
brew install node@22
brew link --overwrite node@22

# Or using nvm
nvm install 22
nvm use 22
nvm alias default 22

Alias Already Exists

Solution: The installer will prompt you to update. Choose 'y' to update or 'n' to keep existing.

To manually remove and reinstall:

# Edit ~/.zprofile and remove the cc() function
nano ~/.zprofile
# Delete the cc() function block

# Run installer again
./create_cc_alias.sh

OTEL Collector Unreachable

Solutions:

1. Start the OTEL collector:

   cd claude-code-otel
   docker-compose up -d

2. Check if Docker is running:

   docker ps

3. Verify port availability:

   lsof -i :4317

4. Skip OTEL setup: Press 's' when prompted to launch without telemetry

Netcat Not Available

This is optional but recommended. To install:

brew install netcat

The script will still work without netcat, but won't test connectivity.

Invalid OTEL Endpoint Format

Solution: Check your endpoint format in ~/.env.cc:

# Correct formats:
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com:4317

# Incorrect formats:
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317  # Missing protocol
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost  # Missing port

Environment Variables Not Loading

Solution: Create or restore the environment file:

# Re-run the installer to create it
./create_cc_alias.sh

# Or manually create it
cat > ~/.env.cc << 'EOF'
CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
EOF

Invalid Environment Variable Format

Solution: Check variable format:

# Correct format:
VARIABLE_NAME=value
ANOTHER_VAR="value with spaces"

# Incorrect format:
VARIABLE NAME=value  # Space in name
export VARIABLE=value  # Don't use 'export'
VARIABLE = value  # Spaces around =

CC Command Not Working

Solutions:

1. Reload your profile:

   source ~/.zprofile

2. Open a new terminal window
3. Verify the function exists:

   grep "cc()" ~/.zprofile

4. Check your shell:

   echo $SHELL  # Should be /bin/zsh

Docker Not Running

Solution: Start Docker Desktop:

1. Open Docker Desktop application
2. Wait for Docker to start (icon turns green)
3. Verify: docker ps

Port Already in Use

Solution: Find and stop the conflicting process:

# Find what's using port 4317
lsof -i :4317

# Find what's using port 3000 (Grafana)
lsof -i :3000

# Kill the process (replace PID with actual process ID)
kill -9 PID

# Or change the port in docker-compose.yml

Grafana Login Issues

Default credentials:

• Username: admin
• Password: admin

To reset admin password:

docker exec -it grafana grafana-cli admin reset-admin-password newpassword

Debug Mode

Enable verbose output for troubleshooting:

# Run installer with debug output
bash -x create_cc_alias.sh

# Test the cc function with debug
set -x
cc
set +x

Manual Cleanup

To completely remove CC alias and start fresh:

# Remove the cc function from ~/.zprofile
sed -i '' '/^cc()/,/^}/d' ~/.zprofile

# Remove environment file
rm ~/.env.cc

# Remove Docker containers (if using)
docker-compose down -v

# Start fresh
./create_cc_alias.sh

Check All Components

Comprehensive system check:

#!/bin/bash
echo "=== System Check ==="
echo "Shell: $SHELL"
echo "Claude: $(which claude || echo 'Not found')"
echo "Node: $(node --version 2>/dev/null || echo 'Not found')"
echo "Docker: $(docker --version 2>/dev/null || echo 'Not found')"
echo "Netcat: $(which nc || echo 'Not found')"
echo ""
echo "=== Configuration Check ==="
echo "Profile exists: $(test -f ~/.zprofile && echo 'Yes' || echo 'No')"
echo "CC function: $(grep -q 'cc()' ~/.zprofile 2>/dev/null && echo 'Yes' || echo 'No')"
echo "Env file: $(test -f ~/.env.cc && echo 'Yes' || echo 'No')"
echo ""
echo "=== OTEL Check ==="
nc -zv localhost 4317 2>&1 || echo "OTEL not reachable"