Troubleshooting

This guide covers common issues you may encounter when using the Kubiya SDK and their solutions.

Authentication Issues

Invalid API Key

Problem: Getting authentication errors even with correct API key. Symptoms:

AuthenticationError: Invalid API key

Solutions:

Verify the API key is correct and not expired
Check the key hasn’t been revoked in the dashboard
Ensure no extra whitespace in the key value
Verify you’re using the correct organization’s key

# Check your API key
import os
from kubiya import ControlPlaneClient

api_key = os.getenv("KUBIYA_API_KEY")
print(f"API Key length: {len(api_key) if api_key else 0}")
print(f"API Key starts with: {api_key[:10] if api_key else 'None'}...")

# Test connection
try:
    client = ControlPlaneClient(api_key=api_key)
    client.datasets.list_datasets()
    print("✅ Authentication successful")
except Exception as e:
    print(f"❌ Authentication failed: {e}")

Environment Variable Not Set

Problem: API key environment variable not being read. Solutions:

Verify environment variable name is exactly KUBIYA_API_KEY
Restart your terminal/IDE after setting the variable
Use .env file with python-dotenv:

from dotenv import load_dotenv
load_dotenv()  # Load from .env file

from kubiya import ControlPlaneClient
client = ControlPlaneClient()  # Will use KUBIYA_API_KEY

Connection Issues

Connection Timeout

Problem: Requests timing out. Symptoms:

TimeoutError: Request timed out after 300 seconds

Solutions:

Increase timeout for long-running operations:

from kubiya import ControlPlaneClient

# Increase timeout to 10 minutes
client = ControlPlaneClient(
    api_key="your-api-key",
    timeout=600
)

Reduce complexity of operations:

# Instead of max_turns=20
result = client.graph.intelligent_search(
    keywords="query",
    max_turns=5  # Reduce complexity
)

Connection Refused

Problem: Unable to connect to Control Plane API. Solutions:

Check your network connectivity
Verify firewall settings allow HTTPS to control-plane.kubiya.ai
Check if you’re behind a proxy:

import os
from kubiya import ControlPlaneClient

# Configure proxy if needed
os.environ['HTTPS_PROXY'] = 'http://proxy.company.com:8080'

client = ControlPlaneClient(api_key="your-api-key")

Data Issues

Empty Results

Problem: Search or recall operations return no results. Solutions:

Verify data exists in the dataset:

# Check dataset status
status = client.datasets.get_dataset_status(dataset_id="your-dataset")
print(f"Status: {status['status']}")
print(f"Progress: {status.get('progress', 0)}%")

Wait for data processing to complete:

import time

while True:
    status = client.datasets.get_dataset_status(dataset_id="dataset-id")
    if status['status'] == 'ready':
        break
    time.sleep(5)

Broaden your search query:

# Too specific - may return nothing
result = client.graph.semantic_search(
    query="exact phrase that might not exist",
    limit=10
)

# Broader query
result = client.graph.semantic_search(
    query="general concept or keywords",
    limit=10
)

Low Relevance Scores

Problem: Semantic search returns results with low similarity scores. Solutions:

Filter results by minimum score:

results = client.graph.semantic_search(query="your query", limit=50)

# Only use high-confidence results
relevant = [r for r in results if r['similarity_score'] > 0.7]

Use intelligent search instead for complex queries:

# Better for complex questions
result = client.graph.intelligent_search(
    keywords="complex multi-part question"
)

Ingestion Issues

Duplicate Node Errors

Problem: Ingestion fails with duplicate node errors. Solution: Use appropriate duplicate handling:

# Skip duplicates
client.ingestion.ingest_nodes_batch(
    nodes=nodes,
    duplicate_handling="skip"
)

# Or update existing nodes
client.ingestion.ingest_nodes_batch(
    nodes=nodes,
    duplicate_handling="update"
)

Batch Import Failures

Problem: Batch ingestion fails partially. Solutions:

Use non-transactional mode:

result = client.ingestion.ingest_nodes_batch(
    nodes=nodes,
    transactional=False  # Don't rollback all on single failure
)

# Check results
print(f"Success: {result['summary']['success']}")
print(f"Failed: {result['summary']['failed']}")

if result.get('errors'):
    for error in result['errors']:
        print(f"Error: {error}")

Reduce batch size:

def import_in_chunks(nodes, chunk_size=100):
    """Import large datasets in smaller chunks."""
    for i in range(0, len(nodes), chunk_size):
        chunk = nodes[i:i + chunk_size]
        result = client.ingestion.ingest_nodes_batch(nodes=chunk)
        print(f"Chunk {i//chunk_size + 1}: {result['summary']['success']} succeeded")

Performance Issues

Slow Responses

Problem: API calls taking longer than expected. Solutions:

Use batch operations:

# ❌ Slow - individual calls
for node in nodes:
    client.ingestion.ingest_node(**node)

# ✅ Fast - batch call
client.ingestion.ingest_nodes_batch(nodes=nodes)

Use async operations for large data:

# Use async for large content
job = client.graph.store_memory_async(
    dataset_id="dataset-id",
    context=large_content
)
# Continue with other work

Implement caching:

from functools import lru_cache

@lru_cache(maxsize=100)
def get_models():
    return client.models.list()

# Subsequent calls use cache
models = get_models()

High Memory Usage

Problem: Application using too much memory. Solutions:

Process data in chunks:

# Instead of loading all at once
skip = 0
while True:
    batch = client.graph.list_memories(skip=skip, limit=100)
    if not batch:
        break

    process_batch(batch)  # Process and discard
    skip += 100

Clear sensitive data from memory:

import gc

secret = client.secrets.get_value(name="api-token")
# Use secret
token = secret['value']
# ... use token ...

# Clear from memory
token = None
secret = None
gc.collect()

Import Errors

Module Not Found

Problem: ModuleNotFoundError: No module named 'kubiya' Solutions:

Verify SDK is installed:

pip list | grep kubiya

Install SDK:

pip install kubiya
# or
pip install kubiya-sdk

Check you’re using the correct Python environment:

which python
python --version

Import Errors for Exceptions

Problem: Cannot import exception classes. Solution: Use correct import paths:

# Core exceptions
from kubiya.core.exceptions import (
    APIError as KubiyaAPIError,
    AuthenticationError as KubiyaAuthenticationError,
    TimeoutError as KubiyaTimeoutError
)

# Resource exceptions
from kubiya.resources.exceptions import (
    GraphError,
    ModelError,
    AgentError
)

SDK Version Issues

Deprecated Methods

Problem: Methods or parameters not working as documented. Solutions:

Check SDK version:

import kubiya
print(f"Kubiya SDK version: {kubiya.__version__}")

Upgrade to latest version:

pip install --upgrade kubiya

Check breaking changes in release notes

Getting Help

If you’re still experiencing issues:

Check SDK Version: Ensure you’re using the latest version
Review Documentation: Check the specific service documentation
Enable Debug Logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Check Status: Verify Control Plane API status
Contact Support: Reach out to Kubiya support with:
- SDK version
- Error message
- Minimal code to reproduce
- Expected vs actual behavior

Common Error Messages

Error Message	Likely Cause	Solution
”Invalid API key”	Wrong or expired key	Verify API key in dashboard
”Dataset not found”	Dataset doesn’t exist	Create dataset first
”Session expired”	Search session timed out	Create new session
”Rate limit exceeded”	Too many requests	Implement backoff and retry
”Validation error”	Invalid parameters	Check parameter types and values
”Connection timeout”	Network issues or slow operation	Increase timeout or reduce complexity
”Node not found”	Referenced node doesn’t exist	Verify node ID or create node first

Next Steps

Error Handling

Learn about exception handling

Best Practices

SDK best practices guide

Examples

Working code examples

API Reference

Complete API documentation

Getting Started

Control Plane API

Control Plane Client

Context Graph & Memory

Client SDK

Workflow DSL

Advanced

Resources

Troubleshooting

Authentication Issues

Invalid API Key

Environment Variable Not Set

Connection Issues

Connection Timeout

Connection Refused

Data Issues

Empty Results

Low Relevance Scores

Ingestion Issues

Duplicate Node Errors

Batch Import Failures

Performance Issues

Slow Responses

High Memory Usage

Import Errors

Module Not Found

Import Errors for Exceptions

SDK Version Issues

Deprecated Methods

Getting Help

Common Error Messages

Next Steps

Error Handling

Best Practices

Examples

API Reference

Getting Started

Control Plane API

Control Plane Client

Context Graph & Memory

Client SDK

Workflow DSL

Advanced

Resources

​Authentication Issues

​Invalid API Key

​Environment Variable Not Set

​Connection Issues

​Connection Timeout

​Connection Refused

​Data Issues

​Empty Results

​Low Relevance Scores

​Ingestion Issues

​Duplicate Node Errors

​Batch Import Failures

​Performance Issues

​Slow Responses

​High Memory Usage

​Import Errors

​Module Not Found

​Import Errors for Exceptions

​SDK Version Issues

​Deprecated Methods

​Getting Help

​Common Error Messages

​Next Steps

Error Handling

Best Practices

Examples

API Reference

Authentication Issues

Invalid API Key

Environment Variable Not Set

Connection Issues

Connection Timeout

Connection Refused

Data Issues

Empty Results

Low Relevance Scores

Ingestion Issues

Duplicate Node Errors

Batch Import Failures

Performance Issues

Slow Responses

High Memory Usage

Import Errors

Module Not Found

Import Errors for Exceptions

SDK Version Issues

Deprecated Methods

Getting Help

Common Error Messages

Next Steps