Troubleshooting

This guide provides solutions for common issues you might encounter when using the RunRL Python client.

Authentication Issues

Invalid API Key

Symptom: You receive an AuthenticationError when initializing the client.

Solution:

Verify that your API key is correct and starts with rl-
Check if your API key has expired or been revoked
Generate a new API key from the RunRL dashboard

try:
    client = RunRL(api_key="rl-your-api-key")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    # Generate a new API key or check the existing one

API Key Environment Variable Not Set

Symptom: You get a ValueError when trying to get the API key from an environment variable.

Solution:

Ensure you've set the environment variable correctly
Check for typos in the environment variable name
Verify the environment variable is accessible in your current session

# Set the environment variable
export RUNRL_API_KEY="rl-your-api-key"

# Verify it's set correctly
echo $RUNRL_API_KEY

File Upload Issues

File Not Found

Symptom: You get a FileNotFoundError when trying to upload a file.

Solution:

Check if the file exists at the specified path
Verify the path is correct (absolute vs. relative)
Ensure you have read permissions for the file

import os

file_path = "path/to/file.jsonl"
if not os.path.exists(file_path):
    print(f"File not found: {file_path}")
    # Handle the error (e.g., prompt for a valid file path)

Invalid File Format

Symptom: Your file upload is rejected by the API.

Solution:

Ensure your file is in the correct format (e.g., .jsonl for prompt files and .py for reward files)
Validate the file content before uploading
Check for any formatting errors in the file

# Example: Validate a JSONL file before uploading
import json

def validate_jsonl(file_path):
    try:
        with open(file_path, 'r') as f:
            for line_num, line in enumerate(f, 1):
                try:
                    json.loads(line)
                except json.JSONDecodeError:
                    print(f"Invalid JSON on line {line_num}: {line}")
                    return False
        return True
    except Exception as e:
        print(f"Error validating file: {e}")
        return False

if validate_jsonl("path/to/file.jsonl"):
    client.upload_prompt_file("path/to/file.jsonl")
else:
    print("File validation failed")

Run Creation Issues

Missing Required Parameters

Symptom: You get a ValueError about missing required arguments when creating a run.

Solution:

Ensure you're providing all required parameters (model_name, prompt_file, reward_file)
Check for typos in parameter names
Verify the parameter values are valid

try:
    run = client.create_run(
        model_name="Qwen/Qwen3-4B",
        prompt_file="file-123",
        reward_file="file-456"
    )
except ValueError as e:
    print(f"Error creating run: {e}")
    # Handle the error (e.g., prompt for missing parameters)

Turbo Mode Constraints

Symptom: You get a ValueError about turbo mode requiring specific GPU settings.

Solution:

When using turbo=True, ensure gpu_type="H100" and n_gpus=8
Alternatively, set turbo=False if you want to use different GPU settings

# Correct configuration for turbo mode
run = client.create_run(
    model_name="Qwen/Qwen3-4B",
    prompt_file="file-123",
    reward_file="file-456",
    gpu_type="H100",
    n_gpus=8,
    turbo=True
)

# Alternative: Disable turbo mode for custom GPU settings
run = client.create_run(
    model_name="Qwen/Qwen3-4B",
    prompt_file="file-123",
    reward_file="file-456",
    gpu_type="A100",
    n_gpus=4,
    turbo=False
)

Resource Not Found Issues

Run Not Found

Symptom: You get a NotFoundError when trying to access a run.

Solution:

Verify the run ID is correct
Check if the run has been deleted
Ensure you have permission to access the run

try:
    run_details = client.get_run_details("run-123")
except NotFoundError as e:
    print(f"Run not found: {e}")
    # List available runs to find the correct ID
    runs = client.list_runs()
    print("Available runs:")
    for run in runs:
        print(f"ID: {run['id']}, Status: {run['status']}")

File Not Found

Symptom: You get a NotFoundError when trying to access a file.

Solution:

Verify the file ID is correct
Check if the file has been deleted
Ensure you have permission to access the file

try:
    file_preview = client.get_prompt_file_preview("file-123")
except NotFoundError as e:
    print(f"File not found: {e}")
    # List available files to find the correct ID
    files = client.list_prompt_files()
    print("Available prompt files:")
    for file in files:
        print(f"ID: {file['id']}, Name: {file['friendly_name']}")

Network and API Issues

Connection Errors

Symptom: You get a RunRLError with a message about HTTP request failure.

Solution:

Check your internet connection
Verify the API endpoint is accessible
Check if there are any firewall or proxy issues

try:
    client.list_runs()
except RunRLError as e:
    if "HTTP request failed" in str(e):
        print("Network connection issue. Please check your internet connection.")
    else:
        print(f"Error: {e}")

API Server Errors

Symptom: You get an APIServerError with a 5xx status code.

Solution:

The issue is on the server side, not your code
Wait and try again later
Check the RunRL status page for any reported outages

import time

max_retries = 3
retry_delay = 5  # seconds

for attempt in range(max_retries):
    try:
        result = client.list_runs()
        break  # Success, exit the loop
    except APIServerError as e:
        print(f"Server error (attempt {attempt+1}/{max_retries}): {e}")
        if attempt < max_retries - 1:
            print(f"Retrying in {retry_delay} seconds...")
            time.sleep(retry_delay)
        else:
            print("Max retries reached. Please try again later.")

Asynchronous Operations

Streaming Logs Issues

Symptom: You get an error when trying to use stream_logs().

Solution:

Ensure you're using the async function correctly
Use asyncio.run() to run the async function from synchronous code
If in an environment that already has an event loop (e.g., Jupyter), use a different approach

# Correct way to use stream_logs in a script
import asyncio

async def stream_logs_example():
    async for log_entry in client.stream_logs("run-123", follow=True):
        print(f"[{log_entry['timestamp']}] {log_entry['message']}")

# Run the async function
asyncio.run(stream_logs_example())

For Jupyter notebooks or environments with an existing event loop:

import nest_asyncio
import asyncio

# Apply nest_asyncio to allow nested event loops
nest_asyncio.apply()

async def stream_logs_example():
    async for log_entry in client.stream_logs("run-123", follow=True):
        print(f"[{log_entry['timestamp']}] {log_entry['message']}")

# Run the async function
await stream_logs_example()

Debugging Tips

Enable Verbose Logging

To get more information about what's happening, you can enable verbose logging:

import logging

# Set up logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Now RunRL client operations will log detailed information
client = RunRL(api_key="rl-your-api-key")

Inspect Request and Response Details

For advanced debugging, you can use a request session with a custom event hook:

import requests
from runrl import RunRL

# Create a session with logging
session = requests.Session()

def log_request_details(response, *args, **kwargs):
    request = response.request
    print(f"Request: {request.method} {request.url}")
    print(f"Response: {response.status_code} {response.reason}")
    
session.hooks["response"] = [log_request_details]

# Use the custom session with RunRL
# Note: This is a hypothetical example and not directly supported by the RunRL client
# You would need to modify the RunRL client to accept a custom session

Common Error Messages and Solutions

Error Message	Likely Cause	Solution
"Authentication failed: Unauthorized"	Invalid API key	Check your API key and regenerate if necessary
"Missing required arguments"	Required parameters not provided	Ensure all required parameters are included
"Resource not found"	Invalid ID or deleted resource	Verify the resource ID and check if it exists
"Permission denied"	Insufficient permissions	Ensure you have the necessary permissions for the operation
"Turbo mode requires 8xH100 GPUs"	Incompatible GPU settings with turbo mode	Use H100 GPUs with n_gpus=8, or set turbo=False
"HTTP request failed"	Network or connectivity issue	Check your internet connection and try again
"Server error"	Issue on the RunRL server	Wait and try again later

Getting Help

If you're still experiencing issues after trying the solutions in this guide:

Check the RunRL documentation for updates
Contact RunRL support at founders@runrl.com
Visit the RunRL dicussion board for help from other users

Troubleshooting

On this page