Skip to main content

​
Common Issues

​
Authentication Issues

​
Cannot Find Developer Token

Problem: You don’t know where to find your API key/developer token. Solution: Generate a developer token from your Aden dashboard:
  1. Log in to your Aden Dashboard
  2. Go to Settings > API Keys
  3. Click on Generate New Key
  4. Copy the key immediately and store it securely
For detailed instructions, see Generate Developer Token.
Store your API key in an environment variable:
export ADEN_API_KEY="your-api-key-here"

​
SSL Certificate Issues

​
SSL Certificate Verification Error (macOS)

Problem: When connecting to kube.acho.io or other HTTPS endpoints, you encounter an SSL certificate verification error similar to: 
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate
This occurs because Python on macOS doesn’t use the system certificate store by default and cannot verify the server’s SSL certificate. Solution (macOS): Run the Install Certificates command that comes with Python: 
/Applications/Python\ 3.x/Install\ Certificates.command
Replace 3.x with your Python version (e.g., 3.11, 3.12). What this does: This command installs the necessary root certificates from the certifi package that Python uses for SSL verification. Alternative Solution: If the command doesn’t work or you installed Python via Homebrew/pyenv, you can install certificates manually: 
pip install --upgrade certifi
Never disable SSL verification in production code (e.g., verify=False). Always fix the certificate issue properly.

​
Installation Issues

​
Package Not Found

Problem: pip install aden-py fails or package is not found. Solution:
  1. Ensure you’re using Python 3.8 or higher:
python --version
  1. Upgrade pip:
pip install --upgrade pip
  1. Try installing again:
pip install aden-py

​
Dependency Conflicts

Problem: Installing aden-py causes conflicts with other packages. Solution: Use a virtual environment to isolate dependencies: 
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install aden-py

​
pip vs pip3 / python vs python3 (macOS)

Problem: The documentation uses pip and python, but you have pip3 and python3 installed on your Mac. Commands like pip install aden-py fail with “command not found”. Why this happens: macOS comes with Python 2.7 pre-installed (older versions), and when you install Python 3, it’s often available as python3 and pip3 to avoid conflicts. The system python command may point to Python 2.7. Solution: Use pip3 and python3 instead of pip and python: 
# Instead of: pip install aden-py
pip3 install aden-py

# Instead of: python --version
python3 --version

# Instead of: python your_script.py
python3 your_script.py
Better Solution - Create Aliases: Add these to your ~/.zshrc or ~/.bash_profile: 
alias python=python3
alias pip=pip3
Then reload your shell: 
source ~/.zshrc  # or source ~/.bash_profile
Best Solution - Use Virtual Environments: This automatically uses the correct Python version: 
python3 -m venv venv
source venv/bin/activate
# Now 'python' and 'pip' automatically point to Python 3
pip install aden-py
python your_script.py
Check which Python version you’re using:
python --version  # or python3 --version
which python      # or which python3

​
Instrumentation Issues

​
No Metrics Being Captured

Problem: After calling instrument(), no metrics are being emitted. Solution:
  1. Verify you’re calling instrument() before importing LLM provider SDKs:
# ✅ Correct order
from aden import instrument, MeterOptions, create_console_emitter

instrument(MeterOptions(
    emit_metric=create_console_emitter(pretty=True),
))

from openai import OpenAI  # Import AFTER instrumentation

# ❌ Incorrect order
from openai import OpenAI  # Too early!
from aden import instrument
instrument(...)
  1. Check that you’re using a supported provider (OpenAI, Anthropic, Gemini).
  2. Verify your emitter is configured correctly. Try using create_console_emitter() for debugging.

​
Async/Await Errors

Problem: Getting errors like RuntimeError: This event loop is already running or instrumentation not working in async contexts. Solution: Use instrument_async() instead of instrument() when working in async contexts: 
# For async applications
from aden import instrument_async, MeterOptions

await instrument_async(MeterOptions(
    api_key=os.environ["ADEN_API_KEY"],
))

​
Connection Issues

​
Cannot Connect to Control Server

Problem: SDK cannot connect to the Aden control server at kube.acho.io. Checklist:
  1. Verify API Key: Ensure your ADEN_API_KEY environment variable is set correctly
  2. Check Network: Verify you can reach the server: 
    curl -I https://kube.acho.io
  3. SSL Certificates: See SSL Certificate Verification Error above
  4. Firewall: Check if your firewall or corporate proxy is blocking the connection

​
Timeout Errors

Problem: Requests to the control server are timing out. Solution:
  1. Check your internet connection
  2. Verify the control server status
  3. If behind a proxy, configure proxy settings:
import os
os.environ['HTTPS_PROXY'] = 'http://proxy.example.com:8080'

​
Getting Help

If you’re still experiencing issues:

GitHub Issues

Report bugs or request features

Documentation

Review the SDK documentation
When reporting issues, please include:
  • Python version (python --version)
  • aden-py version (pip show aden-py)
  • Operating system
  • Minimal code example that reproduces the issue
  • Full error message and stack trace