Troubleshooting

Common issues and solutions.

Authentication

"Invalid API Key" (401)

Error: Invalid API key

Fix:

Get a new key from optixlog.com
Check for typos/spaces
Pass the key directly:

from optixlog import Optixlog

client = Optixlog(api_key="your_api_key")

Verify your key:

key = "your_api_key"
print(f"Key length: {len(key)}")
print(f"Key preview: {key[:10]}...")

Project Issues

"Project not found"

ValueError: Project 'MyProject' not found. Available projects: [...]

Fix 1: Enable auto-create (recommended):

from optixlog import Optixlog

client = Optixlog(api_key="your_api_key")
project = client.project(name="NewProject", create_if_not_exists=True)

Fix 2: List available projects:

from optixlog import list_projects

projects = list_projects(
    api_url="https://optixlog.com",
    api_key="your_api_key"
)
for p in projects:
    print(p.name)

Fix 3: Create manually:

from optixlog import create_project

create_project(
    api_url="https://optixlog.com",
    api_key="your_api_key",
    name="NewProject"
)

Network Issues

"Cannot connect to server"

Fix:

# Test connection
ping optixlog.com

# Check firewall (port 443)
curl https://optixlog.com/health

import requests

try:
    r = requests.get("https://optixlog.com/health", timeout=5)
    print(f"Status: {r.status_code}")
except Exception as e:
    print(f"Failed: {e}")

Custom API URL

If using a self-hosted instance:

from optixlog import Optixlog

client = Optixlog(
    api_key="your_api_key",
    api_url="http://localhost:3000"  # Your instance
)

MPI Issues

MPI Not Detected

Symptoms: is_master always True, rank always 0

Fix:

# Check env vars
echo $OMPI_COMM_WORLD_RANK  # OpenMPI
echo $PMI_RANK              # Intel MPI

# Install mpi4py
pip install mpi4py

# Verify MPI
mpirun --version

Duplicate Logs

Fix: Check is_master:

from optixlog import Optixlog

client = Optixlog(api_key="your_api_key")
project = client.project(name="ParallelSim")
run = project.run(name="mpi_run")

if client.is_master:
    run.log(step=step, value=value)

Workers Hanging

Cause: Unbalanced barrier calls

Fix: All processes must call barrier:

client.barrier()  # Every process must call this

File Upload Issues

"File not found"

Fix:

import os
from optixlog import Optixlog

client = Optixlog(api_key="your_api_key")
project = client.project(name="FileDemo")
run = project.run(name="upload_test")

path = "results.csv"
if os.path.exists(path):
    run.log_file("results", path, "text/csv")
else:
    print(f"File not found: {path}")

# Or use absolute path
abs_path = os.path.abspath("results.csv")
run.log_file("results", abs_path, "text/csv")

Upload Failed (413)

Cause: File too large

Fix:

Compress large files
Split into chunks
Reduce resolution

Validation Errors

"NaN detected"

MetricResult(step=0, ✗ Invalid metrics: NaN detected in 'loss')

Fix:

import numpy as np
from optixlog import Optixlog

client = Optixlog(api_key="your_api_key")
project = client.project(name="Validation")
run = project.run(name="nan_handling")

value = calculate_value()
if np.isfinite(value):
    run.log(step=0, value=value)
else:
    value = np.nan_to_num(value, nan=0.0)
    run.log(step=0, value=value)

"Step must be non-negative"

Fix:

step = max(0, calculated_step)
run.log(step=step, value=value)

Performance Issues

Slow Logging

Fix 1: Reduce frequency:

from optixlog import Optixlog

client = Optixlog(api_key="your_api_key")
project = client.project(name="Optimized")
run = project.run(name="efficient")

for step in range(10000):
    loss = train_step()
    
    if step % 100 == 0:  # Log every 100 steps
        run.log(step=step, loss=loss)

High Memory

Fix: Close matplotlib figures:

import matplotlib.pyplot as plt
from optixlog import Optixlog

client = Optixlog(api_key="your_api_key")
project = client.project(name="Plots")
run = project.run(name="memory_safe")

fig, ax = plt.subplots()
ax.plot(data)
run.log_matplotlib("plot", fig)
plt.close(fig)  # Important!

Import Errors

ModuleNotFoundError

ModuleNotFoundError: No module named 'optixlog'

Fix:

pip show optixlog  # Verify installed

# Reinstall
pip uninstall optixlog
pip install optixlog

ImportError with new API

If upgrading from an old version:

# Old (deprecated)
import optixlog
with optixlog.run(...) as client:
    pass

# New (current)
from optixlog import Optixlog
client = Optixlog(api_key="your_key")
project = client.project(name="MyProject")
run = project.run(name="experiment")

Common Error Codes

Code	Meaning	Solution
401	Invalid API key	Get new key from dashboard
403	Access denied	Check key permissions
404	Not found	Check project/run exists
413	File too large	Compress/split file
500	Server error	Retry or contact support

Debug Checklist

✅ API key is passed to Optixlog(api_key=...)
✅ Python 3.8+ installed
✅ Network connection works
✅ Project exists or create_if_not_exists=True
✅ No NaN/Inf values in metrics
✅ Files exist before upload
✅ MPI: checking client.is_master before logging

Quick Debug Script

from optixlog import Optixlog

# Test your setup
try:
    client = Optixlog(api_key="your_api_key")
    print(f"✓ Client created")
    print(f"  Is master: {client.is_master}")
    print(f"  Rank: {client.rank}/{client.size}")
    
    project = client.project(name="TestProject", create_if_not_exists=True)
    print(f"✓ Project accessed: {project.name}")
    
    run = project.run(name="debug_test")
    print(f"✓ Run created: {run.run_id}")
    
    result = run.log(step=0, test_value=42)
    print(f"✓ Metric logged: {result}")
    
    print("\n✓ All checks passed!")
    
except Exception as e:
    print(f"✗ Error: {e}")

Getting Help

Check error message for hints

Verify SDK version:

import optixlog
print(optixlog.__version__)

Update SDK:
```
pip install --upgrade optixlog
```
Report issues with:
- Error message
- SDK version
- Python version
- Minimal code example

Next Steps

Quick Start — Getting started guide
API Reference — Complete method documentation
Advanced Usage — Power user patterns

Troubleshooting

On this page