Troubleshooting Guide

Common issues and solutions for TAXIA users.

🔍 Quick Diagnosis

Not sure what's wrong? Run the health check:

taxia health

This will show you the status of all components and suggest fixes.

📋 Common Issues

1. Installation Issues

❌ "pip install taxia-core" fails

Error:

ERROR: Could not find a version that satisfies the requirement taxia-core

Solutions:

A. Update pip:

pip install --upgrade pip
pip install taxia-core

B. Check Python version:

python --version  # Must be 3.9 or higher

C. Use specific Python:

python3.11 -m pip install taxia-core

❌ Permission denied during installation

Error:

ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied

Solution:

# Option 1: Use --user flag
pip install --user taxia-core

# Option 2: Use virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install taxia-core

2. API Key Issues

❌ "API key not configured"

Error:

APIError: Anthropic API key not found

Solutions:

A. Set environment variable:

# Linux/Mac
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows PowerShell
$env:ANTHROPIC_API_KEY="sk-ant-..."

# Windows CMD
set ANTHROPIC_API_KEY=sk-ant-...

B. Use .env file:

# Create .env file in your project root
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

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

from taxia import TaxiaEngine
engine = TaxiaEngine()

C. Use demo mode:

from taxia import TaxiaEngine
engine = TaxiaEngine(demo_mode=True)  # No API key needed

❌ "Invalid API key"

Error:

AuthenticationError: Invalid API key provided

Checklist: - [ ] API key has no extra spaces - [ ] API key starts with correct prefix: - Anthropic: sk-ant- - OpenAI: sk- - [ ] API key hasn't expired - [ ] Account has available credits

Test your API key:

# Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json"

# OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

3. Qdrant Connection Issues

❌ "Connection refused: Qdrant"

Error:

ConnectionError: Failed to connect to Qdrant at localhost:6333

Solutions:

A. Check if Qdrant is running:

# Test connection
curl http://localhost:6333/health

# Expected response:
# {"title":"qdrant - vector search engine","version":"..."}

B. Start Qdrant:

# Using Docker (recommended)
docker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant

# Check if it's running
docker ps | grep qdrant

C. Use demo mode (no Qdrant needed):

from taxia import TaxiaEngine
engine = TaxiaEngine(demo_mode=True)

D. Configure different Qdrant host:

from taxia import TaxiaEngine, TaxiaConfig

config = TaxiaConfig(
    qdrant_host="your-qdrant-server.com",
    qdrant_port=6333
)
engine = TaxiaEngine(config=config)

❌ "Collection not found"

Error:

CollectionNotFoundError: Collection 'taxia_documents' does not exist

Solution - Index your data:

# Option 1: Download and index
taxia download --all
taxia index ~/.taxia/data/

# Option 2: Index existing data
taxia index /path/to/your/data

4. Data Issues

❌ "No data found"

Error:

DataNotFoundError: Tax law data not found at ~/.taxia/data/

Solutions:

A. Download data:

# Download all years
taxia download --all

# Download specific year
taxia download --year 2025

# Specify custom directory
taxia download --data-dir /custom/path

B. Verify data location:

# Check default data directory
ls ~/.taxia/data/

# Expected structure:
# 2015/ 2016/ 2017/ ... 2025/

C. Use demo mode:

engine = TaxiaEngine(demo_mode=True)  # Uses built-in sample data

❌ "Data download failed"

Error:

DownloadError: Failed to download data from Hugging Face

Solutions:

A. Check internet connection:

ping huggingface.co

B. Use VPN if blocked: Some regions may block Hugging Face. Try using a VPN.

C. Manual download: 1. Visit Hugging Face Dataset 2. Download files manually 3. Extract to ~/.taxia/data/

D. Retry with timeout:

taxia download --all --timeout 300  # 5 minutes timeout

5. Query Issues

❌ "NoCitationError: Answer lacks citations"

Error:

NoCitationError: Answer must include at least 2 legal citations

Why this happens: TAXIA requires every answer to have legal backing. If no relevant laws are found, it refuses to answer.

Solutions:

A. Make question more specific:

# &#10060; Too vague
result = engine.answer("세금")

# &#9989; Specific
result = engine.answer("법인세법 제27조의 내용은?")

B. Check if data is indexed:

taxia validate  # Verify data integrity

C. Try broader question:

# If very specific query fails, try broader
result = engine.answer("법인세 신고에 대한 일반 규정")

D. Check retrieval settings:

from taxia import TaxiaEngine, TaxiaConfig

config = TaxiaConfig(
    top_k=10  # Retrieve more documents (default: 5)
)
engine = TaxiaEngine(config=config)

❌ Slow responses

Problem: Queries take more than 10 seconds

Solutions:

A. Check LLM response time:

import time
start = time.time()
result = engine.answer("법인세율은?")
print(f"Time: {time.time() - start:.2f}s")

B. Optimize Qdrant:

# Use SSD for Qdrant storage
# Increase Qdrant memory allocation
docker run -d -p 6333:6333 \
  --memory=4g \
  qdrant/qdrant

C. Reduce top_k:

config = TaxiaConfig(top_k=3)  # Retrieve fewer documents
engine = TaxiaEngine(config=config)

D. Use caching:

# Cache frequent queries
cache = {}

def cached_answer(question):
    if question in cache:
        return cache[question]
    result = engine.answer(question)
    cache[question] = result
    return result

❌ Incorrect answers

Problem: Answer doesn't match expected law

Debugging steps:

1. Check citations:

result = engine.answer("법인세율은?")
for citation in result.citations:
    print(citation)
# Verify these are correct sources

2. Verify data version:

# Check which year's data is indexed
ls ~/.taxia/data/
# Make sure you have the right year

3. Test with known question:

# Test with a question you know the answer to
result = engine.answer("법인세법 제1조의 목적은?")
# Verify answer matches actual law

4. Check trace log:

print(f"Trace ID: {result.trace_id}")
# Use this to debug in logs

6. Neo4j (Graph-RAG) Issues

❌ "Neo4j connection failed"

Error:

Neo4jError: Failed to establish connection to Neo4j

Note: Neo4j is optional. TAXIA works without it.

Solutions:

A. Disable Graph-RAG:

from taxia import TaxiaEngine, TaxiaConfig

config = TaxiaConfig(enable_graph_rag=False)
engine = TaxiaEngine(config=config)

B. Start Neo4j:

# Using Docker
docker run -d \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:latest

# Check if running
curl http://localhost:7474

C. Configure Neo4j credentials:

export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="your-password"

7. CLI Issues

❌ "taxia: command not found"

Error:

bash: taxia: command not found

Solutions:

A. Reinstall with scripts:

pip uninstall taxia-core
pip install taxia-core

B. Run as module:

python -m taxia.cli health
python -m taxia.cli query "법인세율은?"

C. Check PATH:

# Find where taxia is installed
pip show taxia-core | grep Location

# Add to PATH (Linux/Mac)
export PATH="$PATH:$HOME/.local/bin"

# Windows
# Add C:\Users\YourName\AppData\Local\Programs\Python\Python39\Scripts to PATH

8. REST API Issues

❌ "Address already in use"

Error:

OSError: [Errno 48] Address already in use

Solutions:

A. Use different port:

taxia server --port 8001  # Instead of default 8000

B. Kill existing process:

# Linux/Mac
lsof -ti:8000 | xargs kill -9

# Windows
netstat -ano | findstr :8000
taskkill /PID <process_id> /F

❌ "CORS errors"

Error in browser:

Access to fetch at 'http://localhost:8000' from origin 'http://localhost:3000' 
has been blocked by CORS policy

Solution:

Configure CORS in your API setup:

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],  # Your frontend URL
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

🔧 Advanced Troubleshooting

Enable Debug Logging

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

from taxia import TaxiaEngine
engine = TaxiaEngine()

Check All Dependencies

pip list | grep -E "taxia|qdrant|anthropic|openai|neo4j"

Verify System Requirements

import sys
print(f"Python: {sys.version}")

import taxia
print(f"TAXIA: {taxia.__version__}")

import qdrant_client
print(f"Qdrant: {qdrant_client.__version__}")

📊 Performance Tuning

Slow Queries?

1. Monitor components:

import time

# Test vector search
start = time.time()
# ... vector search code
print(f"Vector search: {time.time() - start:.2f}s")

# Test LLM
start = time.time()
# ... LLM call
print(f"LLM generation: {time.time() - start:.2f}s")

2. Optimize Qdrant: - Use SSD storage - Increase RAM allocation - Use HNSW index (default)

3. Optimize LLM: - Reduce max_tokens in config - Use faster model (claude-3-haiku) - Implement caching

🚨 Still Need Help?

1. Check Documentation

2. Search GitHub Issues

Existing Issues
Someone may have had the same problem!

3. Create New Issue

4. Provide Debug Information

When reporting issues, include:

# System info
python --version
pip show taxia-core

# Health check
taxia health

# Error message (full traceback)
# Configuration (without sensitive data)
# Steps to reproduce

✅ Issue Resolution Checklist

Before asking for help, verify you've tried:

[ ] Updated to latest version: pip install --upgrade taxia-core
[ ] Checked taxia health output
[ ] Read error message carefully
[ ] Searched this troubleshooting guide
[ ] Searched GitHub issues
[ ] Tried demo mode: TaxiaEngine(demo_mode=True)
[ ] Verified API keys are valid
[ ] Checked Qdrant is running (if not using demo mode)
[ ] Reviewed configuration settings

📞 Community Support

GitHub Discussions: Ask questions and share solutions
GitHub Issues: Report bugs and request features
Documentation: Comprehensive guides and examples

Remember: Most issues have simple solutions. Check the basics first! 🎯