Troubleshooting

Common Issues

Authentication Problems

401 Unauthorized Error

Problem: Getting 401 Unauthorized when making API calls.Causes:

Invalid API key
Expired API key
API key not properly set

Solutions:

# Check if API key is set
import os
api_key = os.getenv("NOXUS_API_KEY")
if not api_key:
    print("API key not found in environment variables")

# Verify API key format
if api_key and not api_key.startswith("noxus_"):
    print("API key format appears incorrect")

# Test authentication
try:
    client = Client(api_key=api_key)
    models = client.get_models()  # Simple test call
    print("✅ Authentication successful")
except httpx.HTTPStatusError as e:
    if e.response.status_code == 401:
        print("❌ Invalid API key")

403 Forbidden Error

Problem: Getting 403 Forbidden when accessing certain resources.Causes:

Insufficient permissions for your workspace role
Trying to access resources from another workspace
API key doesn’t have required permissions

Solutions:

Contact your workspace administrator
Verify you’re using the correct workspace API key
Check your role permissions in the Noxus dashboard

# Check your user permissions
try:
    client = Client(api_key="your_key")
    if client.admin.enabled:
        print("✅ You have admin permissions")
    else:
        print("ℹ️ Limited permissions - some features may not be available")
except Exception as e:
    print(f"❌ Error checking permissions: {e}")

Connection Issues

Network Timeouts

Problem: Requests timing out or taking too long.Solutions:

import httpx
from noxus_sdk.client import Client

# For long-running operations, increase timeout
try:
    client = Client(api_key="your_key")
    # Use async for better timeout handling
    import asyncio
    
    async def with_timeout():
        try:
            result = await asyncio.wait_for(
                client.workflows.alist(),
                timeout=60.0  # 60 second timeout
            )
            return result
        except asyncio.TimeoutError:
            print("Operation timed out")
            return None
    
    workflows = asyncio.run(with_timeout())
except httpx.RequestError as e:
    print(f"Network error: {e}")

Connection Refused

Problem: Cannot connect to the Noxus backend.Causes:

Network connectivity issues
Firewall blocking requests
Incorrect backend URL

Solutions:

import requests

# Test basic connectivity
def test_connectivity():
    try:
        response = requests.get("https://backend.noxus.ai/health", timeout=10)
        if response.status_code == 200:
            print("✅ Backend is reachable")
        else:
            print(f"⚠️ Backend returned status: {response.status_code}")
    except requests.exceptions.ConnectionError:
        print("❌ Cannot connect to backend")
    except requests.exceptions.Timeout:
        print("❌ Connection timed out")

test_connectivity()

# Check if using custom backend URL
backend_url = os.getenv("NOXUS_BACKEND_URL")
if backend_url:
    print(f"Using custom backend: {backend_url}")

Workflow Issues

Workflow Creation Fails

Problem: Cannot create or save workflows.Common Issues:

from noxus_sdk.workflows import WorkflowDefinition

# Issue 1: Missing required node configurations
def check_node_config(workflow_def):
    for node in workflow_def.nodes:
        if node.type == "TextGenerationNode":
            if not hasattr(node.config, 'template') or not node.config.template:
                print(f"❌ Node '{node.label}' missing template")
            if not hasattr(node.config, 'model') or not node.config.model:
                print(f"❌ Node '{node.label}' missing model")

# Issue 2: Invalid connections
def check_connections(workflow_def):
    node_ids = {node.id for node in workflow_def.nodes}
    for edge in workflow_def.edges:
        if edge.source_node_id not in node_ids:
            print(f"❌ Invalid source node: {edge.source_node_id}")
        if edge.target_node_id not in node_ids:
            print(f"❌ Invalid target node: {edge.target_node_id}")

# Issue 3: Orphaned nodes
def check_orphaned_nodes(workflow_def):
    connected_nodes = set()
    for edge in workflow_def.edges:
        connected_nodes.add(edge.source_node_id)
        connected_nodes.add(edge.target_node_id)
    
    orphaned = [node for node in workflow_def.nodes if node.id not in connected_nodes]
    if orphaned:
        print(f"⚠️ Orphaned nodes: {[n.label for n in orphaned]}")

Workflow Execution Fails

Problem: Workflows fail during execution.Debugging Steps:

def debug_workflow_execution(workflow, input_data):
    try:
        # Start workflow
        run = workflow.run(body=input_data)
        print(f"Started run: {run.id}")
        
        # Monitor execution
        while run.status not in ["completed", "failed", "cancelled"]:
            print(f"Status: {run.status}")
            time.sleep(2)
            run = run.refresh()
        
        if run.status == "completed":
            print(f"✅ Success: {run.output}")
        else:
            print(f"❌ Failed: {run.error_message}")
            if hasattr(run, 'error_details'):
                print(f"Details: {run.error_details}")
                
    except Exception as e:
        print(f"❌ Execution error: {e}")

# Test with minimal input
debug_workflow_execution(workflow, {"test_input": "hello world"})

Conversation Issues

Messages Not Working

Problem: Cannot send messages or get responses.Solutions:

from noxus_sdk.resources.conversations import MessageRequest

def debug_conversation(conversation):
    try:
        # Test basic message
        test_message = MessageRequest(content="Hello, can you hear me?")
        response = conversation.add_message(test_message)
        
        if response and response.message_parts:
            print("✅ Conversation working")
            print(f"Response: {response.message_parts}")
        else:
            print("❌ Empty response received")
            
    except Exception as e:
        print(f"❌ Message error: {e}")
        
        # Check conversation settings
        print(f"Model: {conversation.settings.model}")
        print(f"Max tokens: {conversation.settings.max_tokens}")
        print(f"Tools: {len(conversation.settings.tools)}")

debug_conversation(conversation)

Tool Usage Issues

Problem: Conversation tools not working as expected.Debugging:

def debug_tools(conversation):
    print("Enabled tools:")
    for tool in conversation.settings.tools:
        print(f"- {tool.__class__.__name__}: {tool.enabled}")
        
        # Check tool-specific configuration
        if hasattr(tool, 'kb_id'):
            print(f"  KB ID: {tool.kb_id}")
        if hasattr(tool, 'workflow'):
            print(f"  Workflow: {tool.workflow}")

# Test tool usage explicitly
def test_tool_usage(conversation, tool_name):
    try:
        message = MessageRequest(
            content="Test message for tool",
            tool=tool_name
        )
        response = conversation.add_message(message)
        print(f"✅ Tool '{tool_name}' working")
    except Exception as e:
        print(f"❌ Tool '{tool_name}' error: {e}")

debug_tools(conversation)
test_tool_usage(conversation, "web_research")

Knowledge Base Issues

Document Upload Fails

Problem: Cannot upload documents to knowledge base.Solutions:

def debug_kb_upload(kb, file_path):
    import os
    
    # Check file exists and size
    if not os.path.exists(file_path):
        print(f"❌ File not found: {file_path}")
        return
    
    file_size = os.path.getsize(file_path) / (1024 * 1024)  # MB
    print(f"File size: {file_size:.2f} MB")
    
    if file_size > 50:  # Assuming 50MB limit
        print("⚠️ File may be too large")
    
    # Check file type
    file_ext = os.path.splitext(file_path)[1].lower()
    supported_types = kb.document_types or []
    if file_ext.lstrip('.') not in supported_types:
        print(f"❌ Unsupported file type: {file_ext}")
        print(f"Supported types: {supported_types}")
        return
    
    try:
        run_ids = kb.upload_document(files=[file_path])
        print(f"✅ Upload started: {run_ids}")
        
        # Monitor upload progress
        import time
        for _ in range(30):  # Wait up to 5 minutes
            kb.refresh()
            print(f"KB status: {kb.status}")
            if kb.status == "ready":
                break
            time.sleep(10)
            
    except Exception as e:
        print(f"❌ Upload error: {e}")

debug_kb_upload(kb, "document.pdf")

Knowledge Base Not Ready

Problem: Knowledge base stuck in processing state.Solutions:

def check_kb_status(kb):
    kb.refresh()
    print(f"Status: {kb.status}")
    print(f"Total documents: {kb.total_documents}")
    print(f"Trained documents: {kb.trained_documents}")
    print(f"Error documents: {kb.error_documents}")
    
    if kb.error_documents > 0:
        print("⚠️ Some documents failed to process")
        
        # Check individual document status
        documents = kb.list_documents()
        for doc in documents:
            if doc.status == "error":
                print(f"❌ Failed document: {doc.name}")
    
    if kb.status == "processing":
        print("ℹ️ Knowledge base still processing...")
        
        # Check processing runs
        runs = kb.get_runs(status="running")
        print(f"Active runs: {len(runs)}")

check_kb_status(kb)

Performance Issues

Slow Response Times

import time
from contextlib import contextmanager

@contextmanager
def timer():
    start = time.time()
    yield
    end = time.time()
    print(f"Operation took {end - start:.2f} seconds")

# Measure operation times
with timer():
    workflows = client.workflows.list()

# Use async for better performance
import asyncio

async def fast_operations():
    # Run multiple operations concurrently
    tasks = [
        client.workflows.alist(),
        client.conversations.alist(),
        client.knowledge_bases.alist()
    ]

    results = await asyncio.gather(*tasks)
    return results

with timer():
    results = asyncio.run(fast_operations())

Memory Usage

import psutil
import os

def check_memory_usage():
    process = psutil.Process(os.getpid())
    memory_mb = process.memory_info().rss / 1024 / 1024
    print(f"Memory usage: {memory_mb:.2f} MB")

# Monitor memory during operations
check_memory_usage()

# Process large datasets in batches
def process_large_dataset(items, batch_size=10):
    for i in range(0, len(items), batch_size):
        batch = items[i:i + batch_size]
        # Process batch
        yield batch
        check_memory_usage()

# Use generators for large results
def get_all_workflows_generator(client):
    page = 1
    while True:
        workflows = client.workflows.list(page=page, page_size=50)
        if not workflows:
            break
        for workflow in workflows:
            yield workflow
        page += 1

Debugging Tools

Enable Debug Logging

import logging

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

# Enable HTTP request logging
import httpx
httpx_logger = logging.getLogger("httpx")
httpx_logger.setLevel(logging.DEBUG)

# Now all HTTP requests will be logged
client = Client(api_key="your_key")
workflows = client.workflows.list()

Request/Response Inspection

import httpx

class DebugClient(Client):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    def request(self, method, url, **kwargs):
        print(f"🔄 {method} {url}")
        if 'json' in kwargs:
            print(f"📤 Request body: {kwargs['json']}")

        try:
            response = super().request(method, url, **kwargs)
            print(f"✅ Response: {response.status_code}")
            return response
        except Exception as e:
            print(f"❌ Error: {e}")
            raise

# Use debug client
debug_client = DebugClient(api_key="your_key")
workflows = debug_client.workflows.list()

Getting Help

Collect Diagnostic Information

def collect_diagnostics():
    import sys
    import platform

    print("=== Noxus SDK Diagnostics ===")
    print(f"Python version: {sys.version}")
    print(f"Platform: {platform.platform()}")

    try:
        import noxus_sdk
        print(f"Noxus SDK version: {noxus_sdk.__version__}")
    except:
        print("Noxus SDK version: unknown")

    # Test basic connectivity
    try:
        client = Client(api_key=os.getenv("NOXUS_API_KEY"))
        models = client.get_models()
        print(f"✅ API connection working ({len(models)} models available)")
    except Exception as e:
        print(f"❌ API connection failed: {e}")

    # Check environment
    print(f"API key set: {'Yes' if os.getenv('NOXUS_API_KEY') else 'No'}")
    print(f"Backend URL: {os.getenv('NOXUS_BACKEND_URL', 'default')}")

collect_diagnostics()

Contact Support

When contacting support, include:

Error message - Full error text and stack trace
Code snippet - Minimal code that reproduces the issue
Environment - Python version, OS, SDK version
Expected behavior - What you expected to happen
Actual behavior - What actually happened

# Template for bug reports
bug_report_template = """
## Bug Report

**Error Message:**

[Paste full error message here]

**Code to Reproduce:**
```python
[Minimal code that reproduces the issue]

Environment:

Python version:
OS:
Noxus SDK version:
Backend URL:

Expected Behavior: [What you expected to happen] Actual Behavior: [What actually happened] Additional Context: [Any other relevant information] """ print(bug_report_template)

## Next Steps

<CardGroup cols={2}>
  <Card
    title="Best Practices"
    icon="sparkles"
    href="/sdk/workflows/examples"
  >
    Learn best practices for using the SDK effectively
  </Card>
  <Card
    title="API Reference"
    icon="book"
    href="/sdk/api-reference/introduction"
  >
    Detailed API documentation for all SDK features
  </Card>
  <Card
    title="Examples"
    icon="code"
    href="/sdk/workflows/examples"
  >
    Working examples for common use cases
  </Card>
  <Card
    title="Community Support"
    icon="users"
    href="https://noxus.ai/community"
  >
    Get help from the Noxus community
  </Card>
</CardGroup>

Overview

Getting Started

MCP Server

Concepts

Conversations

Workflows

Resources

Guides

API Reference

Common Issues

Authentication Problems

Connection Issues

Workflow Issues

Conversation Issues

Knowledge Base Issues

Performance Issues

Slow Response Times

Memory Usage

Debugging Tools

Enable Debug Logging

Request/Response Inspection

Getting Help

Collect Diagnostic Information

Contact Support

​Common Issues

​Authentication Problems

​Connection Issues

​Workflow Issues

​Conversation Issues

​Knowledge Base Issues

​Performance Issues

​Slow Response Times

​Memory Usage

​Debugging Tools

​Enable Debug Logging

​Request/Response Inspection

​Getting Help

​Collect Diagnostic Information

​Contact Support

Common Issues

Authentication Problems

Connection Issues

Workflow Issues

Conversation Issues

Knowledge Base Issues

Performance Issues

Slow Response Times

Memory Usage

Debugging Tools

Enable Debug Logging

Request/Response Inspection

Getting Help

Collect Diagnostic Information

Contact Support