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:

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

Check Network Connectivity

Verify your application can reach Arcbeam:

Look for Error Messages

Check your application logs for errors from the connector:

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

Wrong Base URL

Make sure you’re connecting to the correct Arcbeam instance:

Some Operations Not Being Traced

Connector Initialized Too Late

The connector must be initialized before creating any LangChain components:

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:
Common fixes:

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

Project ID Issues

”Project not found”

If you’re specifying a project ID and getting errors:
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:
Recommended versions:

Import Errors

”ModuleNotFoundError: No module named ‘arcbeam_connector’”

The connector isn’t installed:

“ModuleNotFoundError: No module named ‘langchain’”

LangChain isn’t installed:

Self-Hosted Arcbeam Issues

Cannot Connect to Local Instance

If running Arcbeam locally:
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:
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:
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

Next Steps

Python Guide

Review the Python integration guide

Observability

Understand what data is captured

View Traces

Explore traces in the dashboard

Support

Contact support for help