Skip to main content
This guide helps you resolve common issues when instrumenting your application with Arcbeam.

Traces Not Appearing in Dashboard

Check Connector Initialization

Make sure you’re calling connector.init() before any LangChain operations:
# ✅ Correct: Init first
connector = ArcbeamLangConnector(...)
connector.init()

model = ChatOpenAI(...)  # Now LangChain operations are traced

# ❌ Wrong: Init after
model = ChatOpenAI(...)

connector = ArcbeamLangConnector(...)
connector.init()  # Too late! Model already created

Verify API Key

Check that your API key is correct:
  1. Log in to Arcbeam
  2. Go to Settings → API Keys
  3. Verify the key exists and matches what you’re using
  4. Try generating a new key if needed
import os

# Check the key is set
api_key = os.environ.get("ARCBEAM_API_KEY")
print(f"Using API key: {api_key[:10]}..." if api_key else "No API key set!")

Check Network Connectivity

Verify your application can reach Arcbeam:
import requests

try:
    response = requests.get("http://platform.arcbeam.ai/health")  # Or your base URL
    print(f"Arcbeam reachable: {response.status_code}")
except Exception as e:
    print(f"Cannot reach Arcbeam: {e}")

Look for Error Messages

Check your application logs for errors from the connector:
# Run your app and look for Arcbeam-related errors
python your_app.py 2>&1 | grep -i arcbeam

Authentication Errors

”Invalid API key” or “Unauthorized”

Causes:
  • API key is incorrect
  • API key was deleted
  • API key doesn’t have access to the project
Solutions:
  1. Copy the API key again from Arcbeam settings
  2. Check for extra spaces when pasting the key
  3. Verify the key starts with sk-
  4. Try creating a new API key
# Verify your API key format
api_key = os.environ.get("ARCBEAM_API_KEY")
if not api_key:
    print("❌ ARCBEAM_API_KEY not set!")
elif not api_key.startswith("sk-"):
    print("❌ API key should start with 'sk-'")
else:
    print(f"✅ API key looks good: {api_key[:10]}...")

Wrong Base URL

Make sure you’re connecting to the correct Arcbeam instance:
# For SaaS
base_url = "http://platform.arcbeam.ai"

# For self-hosted
base_url = "https://your-domain.com"

# For local development
base_url = "http://localhost:5173"

Some Operations Not Being Traced

Connector Initialized Too Late

The connector must be initialized before creating any LangChain components:
# ✅ Correct order
from arcbeam_connector.langchain.connector import ArcbeamLangConnector
from langchain_openai import ChatOpenAI

# 1. Initialize connector first
connector = ArcbeamLangConnector(
    base_url="http://platform.arcbeam.ai",
    api_key="your-api-key-here",
)
connector.init()

# 2. Then create LangChain components
model = ChatOpenAI(model="gpt-4o-mini")

Using Unsupported LangChain Features

Not all LangChain features are automatically traced. If you’re using custom callbacks or unusual patterns, traces might not be captured. Workaround: Stick to standard LangChain patterns (chains, agents, retrievers) which are fully supported.

Performance Issues

High Latency

Traces are sent asynchronously and shouldn’t add latency. If you’re experiencing slowdowns:
  1. Check network latency to Arcbeam
  2. Verify Arcbeam platform is responsive (check status page)
  3. Try reducing trace volume temporarily to isolate the issue

Memory Usage

The connector batches traces before sending. If you’re seeing high memory usage:
  1. Check for trace backlog - if Arcbeam is unreachable, traces queue up
  2. Reduce concurrent requests if running many parallel operations
  3. Verify network connectivity so traces are sent promptly

Environment Variable Issues

Variables Not Loading

If environment variables aren’t being read:
import os

# Debug environment variables
print("Environment variables:")
print(f"  ARCBEAM_API_KEY: {'✅ Set' if os.environ.get('ARCBEAM_API_KEY') else '❌ Not set'}")
print(f"  ARCBEAM_ENVIRONMENT: {os.environ.get('ARCBEAM_ENVIRONMENT', '❌ Not set')}")
print(f"  OPENAI_API_KEY: {'✅ Set' if os.environ.get('OPENAI_API_KEY') else '❌ Not set'}")
Common fixes:
# Make sure to export variables
export ARCBEAM_API_KEY=your-key-here  # ✅ export keyword
ARCBEAM_API_KEY=your-key-here  # ❌ missing export

# Load from .env file
pip install python-dotenv
from dotenv import load_dotenv
load_dotenv()  # Load variables from .env file

Using .env Files

If using a .env file:
  1. Make sure the file exists in your project root
  2. Add .env to .gitignore (don’t commit it!)
  3. Load it before accessing variables
# .env file
ARCBEAM_API_KEY=sk-your-api-key-here
ARCBEAM_ENVIRONMENT=dev
OPENAI_API_KEY=your-openai-key
from dotenv import load_dotenv
import os

load_dotenv()  # Must call this first!

api_key = os.environ.get("ARCBEAM_API_KEY")

Project ID Issues

”Project not found”

If you’re specifying a project ID and getting errors:
# Verify the project ID is a valid UUID
import uuid

project_id = "f60a7195-665f-4014-8bb3-805ae4337aa9"
try:
    uuid.UUID(project_id)
    print("✅ Valid UUID")
except ValueError:
    print("❌ Invalid UUID format")
Solutions:
  1. Copy the project ID from the Arcbeam dashboard (Projects page)
  2. Check for typos in the UUID
  3. Try omitting project_id to use the default project
  4. Verify the project exists and you have access to it

LangChain Version Issues

Incompatible LangChain Version

The Arcbeam connector requires specific LangChain versions. Check your versions:
pip show langchain langchain-openai langgraph
Recommended versions:
pip install --upgrade langchain langchain-openai
pip install --upgrade langgraph  # If using LangGraph

Import Errors

”ModuleNotFoundError: No module named ‘arcbeam_connector’”

The connector isn’t installed:
pip install arcbeam-connector

“ModuleNotFoundError: No module named ‘langchain’”

LangChain isn’t installed:
pip install langchain langchain-openai

Self-Hosted Arcbeam Issues

Cannot Connect to Local Instance

If running Arcbeam locally:
# Use localhost for local development
connector = ArcbeamLangConnector(
    base_url="http://localhost:5173",  # Not https for local
    api_key="your-api-key-here",
)
Common issues:
  1. Wrong port - Default is 5173, verify your instance
  2. Using https instead of http for localhost
  3. Firewall blocking the connection
  4. Arcbeam not running - check docker ps or your deployment

SSL Certificate Errors

For self-hosted instances with custom SSL:
import os

# Disable SSL verification for development (not recommended for production!)
os.environ["CURL_CA_BUNDLE"] = ""
Better solution: Add your SSL certificate to your system’s trust store.

Still Having Issues?

If you’re still experiencing problems:
1

Check the logs

Look for error messages in your application logs. The connector will log errors if trace sending fails.
2

Try a minimal example

Test with a simple script to isolate the issue:
from langchain_openai import ChatOpenAI
from arcbeam_connector.langchain.connector import ArcbeamLangConnector
import os

connector = ArcbeamLangConnector(
    base_url="http://platform.arcbeam.ai",
    api_key=os.environ.get("ARCBEAM_API_KEY"),
)
connector.init()

model = ChatOpenAI(model="gpt-4o-mini")
result = model.invoke("Hello!")
print(result.content)
3

Check Arcbeam status

Verify the Arcbeam platform is operational (check status page or contact support).
4

Contact support

Email support@arcbeam.ai with:
  • Your error messages
  • Code snippet showing how you’re initializing the connector
  • LangChain and connector versions
  • Whether you’re using cloud or self-hosted Arcbeam

Debugging Checklist

Before contacting support, verify:
  • connector.init() is called before LangChain operations
  • ARCBEAM_API_KEY environment variable is set
  • API key is correct (starts with sk-)
  • Can reach Arcbeam platform (curl http://platform.arcbeam.ai)
  • Using compatible LangChain versions
  • No error messages in application logs
  • Firewall/network allows outbound HTTP to Arcbeam

Common Error Messages

ErrorCauseSolution
Invalid API keyWrong or deleted API keyCopy key again from Arcbeam settings
Project not foundInvalid project_idVerify UUID from dashboard or omit to use default
Connection refusedCannot reach ArcbeamCheck network, firewall, and base_url
Module not foundPackage not installedRun pip install arcbeam-connector
No traces appearingConnector not initializedCall connector.init() before LangChain

Next Steps