Chatkit Debug

Skill: ChatKit Debug & Troubleshooting

Metadata

• Name: chatkit-debug
• Category: debug
• Tags: chatkit, debug, troubleshooting, errors

Description

Diagnoses and fixes common ChatKit integration issues across backend and frontend.

Quick Diagnostic Checklist

Backend Health Check

# 1. Check server starts
python backend/main.py

# 2. Test health endpoint
curl http://localhost:8000/health

# 3. Check for import errors in logs

Frontend Health Check

# 1. Check dev server starts
cd frontend && npm run dev

# 2. Open browser console for errors
# 3. Check Network tab for /chatkit requests

Error Database

Backend Import Errors

Backend Runtime Errors

Frontend Errors

Diagnostic Scripts

Check All Imports

# Run this to verify all imports work
try:
    from chatkit.server import ChatKitServer, StreamingResult
    print("✓ chatkit.server imports OK")
except ImportError as e:
    print(f"✗ chatkit.server: {e}")

try:
    from chatkit.store import Store
    print("✓ chatkit.store imports OK")
except ImportError as e:
    print(f"✗ chatkit.store: {e}")

try:
    from chatkit.types import ThreadMetadata, ThreadItem, Page
    print("✓ chatkit.types imports OK")
except ImportError as e:
    print(f"✗ chatkit.types: {e}")

try:
    from chatkit.agents import AgentContext, stream_agent_response
    print("✓ chatkit.agents imports OK")
except ImportError as e:
    print(f"✗ chatkit.agents: {e}")

try:
    from agents import Agent, Runner
    from agents.extensions.models.litellm_model import LitellmModel
    print("✓ agents imports OK")
except ImportError as e:
    print(f"✗ agents: {e}")

Check Store Implementation

# Verify all abstract methods are implemented
import inspect
from chatkit.store import Store

required_methods = [
    'generate_thread_id',
    'generate_item_id',
    'load_thread',
    'save_thread',
    'load_thread_items',
    'add_thread_item',
    'save_item',
    'load_item',
    'delete_thread_item',
    'load_threads',
    'delete_thread',
    'save_attachment',
    'load_attachment',
    'delete_attachment',
]

# Check your store class
from your_module import YourStore

for method in required_methods:
    if hasattr(YourStore, method):
        print(f"✓ {method}")
    else:
        print(f"✗ {method} - MISSING!")

Test Conversation Memory

# Add to your server for debugging
async def _build_conversation_history(self, thread, current_input, context):
    page = await self.store.load_thread_items(thread.id, None, 100, "asc", context)

    print(f"\n=== CONVERSATION DEBUG ===")
    print(f"Thread: {thread.id}")
    print(f"Items in store: {len(page.data)}")

    for i, item in enumerate(page.data):
        item_type = type(item).__name__
        text = self._extract_text(item)[:50] + "..." if len(self._extract_text(item)) > 50 else self._extract_text(item)
        print(f"  {i+1}. [{item_type}] {text}")

    print(f"=========================\n")

    # ... rest of method

Network Debugging

Check Request/Response

// Add to browser console
const originalFetch = window.fetch;
window.fetch = async (...args) => {
  console.log('Fetch:', args[0]);
  const response = await originalFetch(...args);
  console.log('Response:', response.status, response.headers.get('content-type'));
  return response;
};

Expected Response Types

• POST /chatkit for streaming: text/event-stream
• POST /chatkit for JSON: application/json

Common Fixes Summary

Backend

1. Use chatkit.store not chatkit.stores
2. Use chatkit.types not chatkit.models
3. Implement ALL 14 Store methods
4. Build full conversation history for agent

Frontend

1. Add CDN script to index.html
2. Add domainKey: 'localhost'
3. Use label not name in prompts
4. Remove icon property
5. Persist thread ID in localStorage

Related Skills

• chatkit-backend - Backend setup
• chatkit-frontend - Frontend setup
• chatkit-store - Store implementation
• chatkit-agent-memory - Conversation history