> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcbeam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common issues when sending traces to Arcbeam

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:

```python theme={null}
# ✅ 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

```python theme={null}
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:

```python theme={null}
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:

```bash theme={null}
# 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**

```python theme={null}
# 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:

```python theme={null}
# 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:

```python theme={null}
# ✅ 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:

```python theme={null}
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:**

```bash theme={null}
# 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
```

```python theme={null}
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 theme={null}
# .env file
ARCBEAM_API_KEY=sk-your-api-key-here
ARCBEAM_ENVIRONMENT=dev
OPENAI_API_KEY=your-openai-key
```

```python theme={null}
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:

```python theme={null}
# 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:**

```bash theme={null}
pip show langchain langchain-openai langgraph
```

**Recommended versions:**

```bash theme={null}
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:

```bash theme={null}
pip install arcbeam-connector
```

### "ModuleNotFoundError: No module named 'langchain'"

LangChain isn't installed:

```bash theme={null}
pip install langchain langchain-openai
```

## Self-Hosted Arcbeam Issues

### Cannot Connect to Local Instance

If running Arcbeam locally:

```python theme={null}
# 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:

```python theme={null}
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:

<Steps>
  <Step title="Check the logs">
    Look for error messages in your application logs. The connector will log errors if trace sending fails.
  </Step>

  <Step title="Try a minimal example">
    Test with a simple script to isolate the issue:

    ```python theme={null}
    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)
    ```
  </Step>

  <Step title="Check Arcbeam status">
    Verify the Arcbeam platform is operational (check status page or contact support).
  </Step>

  <Step title="Contact support">
    Email [support@arcbeam.ai](mailto: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
  </Step>
</Steps>

## 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

| Error                 | Cause                     | Solution                                          |
| --------------------- | ------------------------- | ------------------------------------------------- |
| `Invalid API key`     | Wrong or deleted API key  | Copy key again from Arcbeam settings              |
| `Project not found`   | Invalid project\_id       | Verify UUID from dashboard or omit to use default |
| `Connection refused`  | Cannot reach Arcbeam      | Check network, firewall, and base\_url            |
| `Module not found`    | Package not installed     | Run `pip install arcbeam-connector`               |
| `No traces appearing` | Connector not initialized | Call `connector.init()` before LangChain          |

## Next Steps

<CardGroup cols={2}>
  <Card title="Python Guide" icon="python" href="/v0/integrations/ai-frameworks/langchain">
    Review the Python integration guide
  </Card>

  <Card title="Observability" icon="list" href="/v0/core-concepts/observability">
    Understand what data is captured
  </Card>

  <Card title="View Traces" icon="eye" href="/v0/debugging/find-problematic-traces">
    Explore traces in the dashboard
  </Card>

  <Card title="Support" icon="envelope" href="mailto:support@arcbeam.ai">
    Contact support for help
  </Card>
</CardGroup>