Troubleshooting with AI

Overview

This guide covers common Trix memory platform integration issues and how to debug them effectively using AI coding assistants. Each problem includes symptoms, root causes, and AI prompts to generate solutions.

Connection & Authentication

API Key Validation Failures

Symptoms:

• 401 Unauthorized responses from the Trix API
• API key rejected despite being copied correctly
• Authentication works in one environment but not another

Root Cause: Invalid API key, wrong environment, or missing authorization header.

AI Prompt:

I'm getting 401 Unauthorized from the Trix API:

Error: [paste exact error message]

Setup:
- SDK: [Python/TypeScript/C#/REST]
- Base URL: [your API URL]
- API key source: [environment variable/config file/hardcoded]

Current code:
[paste your client initialization code]

Help me:
1. Verify the API key format is correct
2. Check the authorization header is set properly
3. Confirm the base URL matches my environment
4. Add proper error handling for auth failures

Common Solutions:

• Verify API key starts with the expected prefix
• Check the Authorization: Bearer header is set correctly
• Ensure the base URL matches your environment (production vs. staging)
• Regenerate the API key if it may have been revoked

Network Connection Errors

Symptoms:

• Connection refused or timeout errors
• DNS resolution failures
• SSL/TLS certificate errors

Root Cause: Network configuration, firewall rules, or incorrect base URL.

AI Prompt:

I can't connect to the Trix API:

Error: [paste exact error - ECONNREFUSED, timeout, SSL error, etc.]

Environment:
- Running from: [local machine/Docker/CI/cloud]
- Base URL: [your configured URL]
- Proxy: [yes/no, details]

Help me:
1. Diagnose the connection issue
2. Test connectivity to the API endpoint
3. Check firewall or proxy settings
4. Configure SSL properly if needed

Network details: [any relevant proxy/firewall info]

Common Solutions:

• Verify the API base URL is correct and reachable
• Check if a proxy or VPN is blocking the connection
• Ensure DNS can resolve the API hostname
• For Docker: use host network or ensure proper DNS resolution

MCP Setup

MCP Server Not Starting

Symptoms:

• Claude Desktop shows "server not connected"
• MCP tools don't appear in Claude's tool list
• Server process crashes immediately on start

Root Cause: Missing environment variables, incorrect config path, or dependency issues.

AI Prompt:

Trix MCP server won't start or connect to Claude Desktop:

Error: [paste error from Claude Desktop or server logs]

Config file:
[paste your claude_desktop_config.json MCP section]

Environment:
- OS: [macOS/Windows/Linux]
- Node.js version: [version]
- Claude Desktop version: [version]

Help me:
1. Verify the MCP server configuration is correct
2. Check that required environment variables are set
3. Test the MCP server independently
4. Debug the connection between Claude Desktop and the server

Common Solutions:

• Set TRIX_API_KEY and TRIX_BASE_URL in environment
• Verify the MCP server path in Claude Desktop config is absolute
• Check Node.js version is 18+ (required for MCP)
• Run the MCP server manually to see startup errors

MCP Tool Not Found

Symptoms:

• Specific Trix tools missing from Claude's tool list
• "Tool not found" errors when Claude tries to use a Trix tool
• Some tools work but others don't

Root Cause: Outdated MCP server version or tool name mismatch.

AI Prompt:

Some Trix MCP tools are missing or not working:

Missing tools: [list which tools]
Working tools: [list which tools work]
MCP server version: [version]

Help me:
1. Check the MCP server version and update if needed
2. Verify tool names match the current API
3. List all available tools to find the correct names
4. Debug why specific tools fail to register

Common Solutions:

• Update trix-mcp to the latest version
• Check the tool name matches exactly (e.g., store_memory not storeMemory)
• Restart Claude Desktop after config changes
• Verify API key has permissions for the requested operations

SDK Issues

Import and Installation Errors

Symptoms:

• Module not found errors when importing the SDK
• Type errors after installation
• Version conflicts with other dependencies

Root Cause: Incorrect installation, version mismatch, or module resolution issues.

AI Prompt:

I'm getting import errors with the Trix SDK:

Error: [paste exact error message]

Setup:
- SDK: [trixdb (Python) / @trixdb/client (TS) / Trix (C#)]
- Version: [installed version]
- Runtime: [Python 3.x / Node.js x / .NET x]
- Package manager: [pip/npm/NuGet]

Current import:
[paste your import statement]

Help me:
1. Fix the import error
2. Verify the correct package is installed
3. Check for version compatibility
4. Set up proper module resolution

Common Solutions:

• Verify the package name is correct for your SDK language
• Check you're importing from the right module path
• Clear package cache and reinstall: pip install --force-reinstall or npm ci
• Ensure runtime version meets minimum requirements

Rate Limiting Errors

Symptoms:

• 429 Too Many Requests responses
• Requests fail after working for a while
• Batch operations partially fail

Root Cause: Exceeding API rate limits, especially during batch operations.

AI Prompt:

I'm hitting Trix API rate limits:

Error: [paste exact error response]

What I'm doing:
- Operation: [batch store/search/enrich]
- Request count: ~[N] requests per [time period]
- Batch size: [if applicable]

Current code:
[paste your code]

Help me:
1. Understand the rate limit I'm hitting
2. Implement exponential backoff retry logic
3. Optimize batch sizes (max 100 per batch for stores)
4. Add request throttling to stay under limits

Common Solutions:

• Implement exponential backoff with jitter on 429 responses
• Use batch endpoints instead of individual requests
• Keep batch sizes under 100 for memory stores
• Add delays between batch operations

Timeout Configuration

Symptoms:

• Requests timeout during enrichment or deep search
• Large batch operations fail with timeout errors
• Connections drop during long-running operations

Root Cause: Default timeout too short for heavy operations like enrichment.

AI Prompt:

Trix API requests are timing out:

Error: [paste timeout error]

Operation: [enrichment/deep search/batch store]
Default timeout: [current value]
Typical response time: [if known]

Help me:
1. Configure appropriate timeouts for different operations
2. Set longer timeouts for enrichment (can take 30s+)
3. Implement request-level timeout overrides
4. Add timeout handling and retry logic

SDK: [Python/TypeScript/C#]

Common Solutions:

• Set enrichment timeout to 60s+ (enrichment batches can be slow)
• Use 10-memory batches for enrichment to avoid gateway timeouts
• Configure per-request timeout overrides for heavy operations
• Implement async polling for long-running operations

Search Problems

No Search Results Returned

Symptoms:

• Searches return empty results despite memories existing
• Semantic search finds nothing but fulltext search works
• Results don't match the query intent

Root Cause: Missing embeddings, wrong space, or query too specific.

AI Prompt:

Trix search returns no results even though I have memories stored:

Search query: [your query]
Search type: [semantic/fulltext/hybrid]
Space: [space ID]
Memory count in space: [approximate count]

Code:
[paste your search code]

Help me:
1. Verify memories exist in the correct space
2. Check if embeddings have been generated
3. Try different search types (semantic vs. fulltext)
4. Broaden the query to test basic retrieval
5. Check if enrichment completed successfully

Common Solutions:

• Verify the space ID matches where memories were stored
• Run enrichment on memories to generate embeddings
• Try fulltext_search to confirm memories are queryable
• Broaden your query -- overly specific queries may miss semantic matches

Low Relevance Scores

Symptoms:

• Search results don't match the intent of the query
• Irrelevant memories ranked higher than relevant ones
• Relevance scores are consistently low

Root Cause: Poor memory quality, missing enrichment, or suboptimal query phrasing.

AI Prompt:

Trix search returns results but they're not relevant:

Query: [your query]
Expected results: [describe what you expected]
Actual results: [describe what you got]
Relevance scores: [typical scores you see]

Help me:
1. Improve search query phrasing
2. Use search_with_explanation to understand ranking
3. Check memory quality and enrichment status
4. Try topic-based search for better precision
5. Use filters (tags, date range) to narrow results

Common Solutions:

• Enrich memories to improve embedding quality
• Use search_with_explanation to debug why results ranked as they did
• Combine semantic search with tag or topic filters
• Store memories with clear, descriptive content (not just raw text)

CLI Issues

Config File Not Found

Symptoms:

• CLI reports "config not found" on startup
• Commands fail with missing configuration errors
• Default settings used instead of custom config

Root Cause: Config file not in expected location or wrong format.

AI Prompt:

The Trix CLI can't find my configuration:

Error: [paste exact error]

OS: [macOS/Windows/Linux]
Config location: [where you put the config file]
Config content:
[paste your config file]

Help me:
1. Find the correct config file location for my OS
2. Verify the config file format is valid
3. Set API key and base URL correctly
4. Test the CLI connection after fixing config

Common Solutions:

• Check the default config path: ~/.config/trix/config.yaml
• Set the config path explicitly with --config flag
• Use environment variables as an alternative: TRIX_API_KEY, TRIX_BASE_URL
• Verify YAML/JSON syntax in the config file

CLI Authentication Errors

Symptoms:

• CLI commands return "unauthorized" or "forbidden"
• Login succeeds but subsequent commands fail
• Token expired errors

Root Cause: Invalid or expired credentials in CLI configuration.

AI Prompt:

Trix CLI authentication isn't working:

Error: [paste exact error]
Command that fails: [the command you ran]

Setup:
- CLI version: [version]
- Auth method: [API key/login]
- Base URL: [configured URL]

Help me:
1. Re-authenticate with the CLI
2. Verify API key is valid and not expired
3. Check the base URL is correct
4. Debug the auth flow to find where it fails

Common Solutions:

• Re-run the login command to refresh credentials
• Check that the API key hasn't been revoked or rotated
• Verify the base URL matches your API environment
• Clear cached credentials and re-authenticate

Effective Debugging Strategies

Collect Information

Before asking AI for help, gather:

• Exact error messages - Copy full errors from console or logs
• Relevant code - Include client initialization, API calls, and error handling
• Environment details - SDK language, version, runtime, OS
• Reproduction steps - What actions trigger the issue
• Expected vs. actual - What should happen vs. what does happen

Iterative Debugging

1. Start broad - Ask AI to analyze the full error context
2. Narrow down - Follow up with specific questions
3. Test solutions - Try suggested fixes one at a time
4. Share results - Tell AI what worked or didn't
5. Refine - Iterate until the issue is resolved

Example Debugging Session

# First prompt
"My Trix semantic search returns no results. Here's my code: [code]
Space has ~500 memories stored."

# AI suggests: check if embeddings exist, try fulltext search first
# You try it...

# Follow-up
"Fulltext search works! Semantic search still returns nothing.
Enrichment status shows 'pending' for most memories."

# AI suggests: run enrichment to generate embeddings
# You try it...

# Final check
"After enrichment, semantic search works. Can you review my
enrichment pipeline to make sure new memories get enriched automatically?"

Getting Better Help from AI

When to Use Different AI Tools

Next Steps

• Prompt Library - Pre-written prompts for common tasks
• Claude Code - Debugging with Claude Code
• Cursor - Quick fixes with Cursor
• Trix Support - Documentation and support resources