Skip to Content
SdkSDK Troubleshooting

SDK Troubleshooting

Common issues and solutions when using OptixLog SDK.

Authentication Errors

Error: “Missing OPTIX_API_KEY”

Symptoms:

ValueError: Missing OPTIX_API_KEY. Set it via environment variable or pass api_key parameter.

Solutions:

  1. Set environment variable:

    export OPTIX_API_KEY="proj_your_key_here"

  2. Pass directly:

    client = optixlog.init(api_key="proj_your_key_here", ...)

  3. Check if set:

    import os
print(os.getenv("OPTIX_API_KEY"))  # Should print your key

Error: “Invalid API Key” (401)

Symptoms:

ValueError: ❌ Invalid API Key. Please check your API key and try again.

Solutions:

  1. Verify your API key:

  2. Check key format:

    api_key = os.getenv("OPTIX_API_KEY")
print(f"Key length: {len(api_key)}")  # Should be reasonable length
print(f"Key starts with 'proj_': {api_key.startswith('proj_')}")

  3. Test with explicit key:

    client = optixlog.init(
    api_key="proj_YOUR_KEY_HERE",
    run_name="test"
)

Error: “API Key access denied” (403)

Symptoms:

ValueError: ❌ API Key access denied. Your API key may not have the required permissions.

Solutions:

  1. Check key permissions - Some keys may have restricted access
  2. Get a new key from the web dashboard
  3. Contact support if issue persists

Project Errors

Error: “Project ‘X’ not found”

Symptoms:

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

Solutions:

  1. Use auto-create:

    with optixlog.run(
    "my_run",
    project="NewProject",
    create_project_if_not_exists=True  # Default: True for optixlog.run()
) as client:
    pass

  2. List available projects:

    projects = optixlog.list_projects(api_url, api_key)
for p in projects:
    print(p.name)

  3. Create project manually:

    optixlog.create_project(api_url, api_key, "NewProject")

Error: “Failed to create project”

Symptoms:

ValueError: ❌ Failed to create project (500): ...

Solutions:

  1. Check if project already exists (may be owned by another user)
  2. Try a different project name
  3. Check server status

Network Connectivity Issues

Error: “Cannot connect to OptixLog server”

Symptoms:

ValueError: Cannot connect to OptixLog server

Solutions:

  1. Check internet connection:

    ping backend.optixlog.com

  2. Verify API URL:

    # Default URL
api_url = "https://backend.optixlog.com"
 
# Or set custom
export OPTIX_API_URL="https://your-custom-url.com"

  3. Check firewall/proxy:

    • Ensure port 443 (HTTPS) is open
    • Configure proxy if needed

  4. Test connection:

    import requests
try:
    r = requests.get("https://backend.optixlog.com/health", timeout=5)
    print(f"Server status: {r.status_code}")
except Exception as e:
    print(f"Connection failed: {e}")

MPI Detection Problems

Issue: MPI Not Detected

Symptoms:

  • is_master is always True
  • rank is always 0
  • size is always 1

Solutions:

  1. Check environment variables:

    # OpenMPI
echo $OMPI_COMM_WORLD_RANK
echo $OMPI_COMM_WORLD_SIZE
 
# Intel MPI
echo $PMI_RANK
echo $PMI_SIZE

  2. Install mpi4py:

    pip install mpi4py

  3. Verify MPI installation:

    mpirun --version
which mpirun

  4. Test MPI:

    try:
    from mpi4py import MPI
    comm = MPI.COMM_WORLD
    print(f"Rank: {comm.Get_rank()}, Size: {comm.Get_size()}")
except ImportError:
    print("mpi4py not installed")

Issue: All Processes Logging

Symptoms: Duplicate logs from all MPI processes

Solution: Always check is_master:

with optixlog.run("parallel") as client:
    if client.is_master:
        client.log(step=step, value=value)

File Upload Failures

Error: “File not found”

Symptoms:

ValueError: ✗ Invalid file: File not found: /path/to/file.csv

Solutions:

  1. Check file path:

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

  2. Use absolute paths:

    import os
abs_path = os.path.abspath("results.csv")
client.log_file("results", abs_path)

  3. Check permissions:

    import os
if os.access("results.csv", os.R_OK):
    client.log_file("results", "results.csv")

Error: “Upload failed”

Symptoms:

MediaResult(key='file', ✗ Upload failed (413))

Solutions:

  1. Check file size - May exceed server limits
  2. Compress large files before uploading
  3. Split large files into smaller chunks
  4. Check network connection

Image Format Issues

Error: “Invalid image”

Symptoms:

MediaResult(key='plot', ✗ Invalid image: ...)

Solutions:

  1. Use helper method (recommended):

    # Automatically handles conversion
client.log_matplotlib("plot", fig)

  2. Check PIL Image format:

    from PIL import Image
img = Image.open("plot.png")
print(f"Format: {img.format}, Size: {img.size}, Mode: {img.mode}")

  3. Convert to RGB if needed:

    if img.mode != 'RGB':
    img = img.convert('RGB')
client.log_image("plot", img)

Validation Errors

Error: “Invalid metrics: NaN detected”

Symptoms:

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

Solutions:

  1. Check for NaN/Inf:

    import numpy as np
 
value = calculate_value()
if np.isfinite(value):
    client.log(step=0, value=value)
else:
    print(f"Warning: Invalid value {value}")

  2. Replace NaN with default:

    value = calculate_value()
if np.isnan(value):
    value = 0.0  # or appropriate default
client.log(step=0, value=value)

  3. Use numpy functions:

    value = np.nan_to_num(calculate_value(), nan=0.0)
client.log(step=0, value=value)

Error: “Invalid step: Step must be non-negative”

Symptoms:

MetricResult(step=-1, ✗ Invalid step: Step must be non-negative)

Solution:

# Ensure step is non-negative
step = max(0, calculated_step)
client.log(step=step, value=value)

Performance Issues

Issue: Slow Logging

Symptoms: Logging takes too long, slows down simulation

Solutions:

  1. Use batch operations:

    # Slow
for step in range(1000):
    client.log(step=step, loss=losses[step])
 
# Fast
metrics = [{"step": i, "loss": losses[i]} for i in range(1000)]
client.log_batch(metrics)

  2. Reduce logging frequency:

    # Log every 10 steps instead of every step
for step in range(1000):
    if step % 10 == 0:
        client.log(step=step, loss=losses[step])

  3. Log asynchronously (if supported):

    # Queue logs and upload in background
# (Implementation depends on your needs)

Issue: High Memory Usage

Symptoms: Memory usage grows during logging

Solutions:

  1. Close matplotlib figures:

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

  2. Use helper methods (auto-cleanup):

    # Helper methods automatically close figures
client.log_plot("plot", x, y)

  3. Clear large arrays after logging:

    field = get_field()
client.log_array_as_image("field", field)
del field  # Free memory

Common Error Messages

”Server error (500)”

Cause: Internal server error

Solutions:

  1. Wait a moment and retry
  2. Check server status
  3. Contact support if persistent

”Server error (404)”

Cause: Endpoint not found

Solutions:

  1. Check API URL is correct
  2. Verify you’re using the latest SDK version
  3. Check server is running

”Timeout”

Cause: Request took too long

Solutions:

  1. Check network connection
  2. Reduce file sizes
  3. Use batch operations for efficiency

Getting Help

If you encounter an issue not covered here:

  1. Check the error message - It often contains helpful hints
  2. Verify your setup - API key, project, network
  3. Check SDK version: 
    import optixlog
print(optixlog.__version__)
  4. Update SDK: 
    pip install --upgrade http://optixlog.com/optixlog-0.0.4-py3-none-any.whl
  5. Report the issue with:
    • Error message
    • SDK version
    • Python version
    • Code snippet (if possible)

Next Steps

SDK Quick Start