Troubleshooting Guide

Symptoms

• Claude says "Stompy tools not available"
• SSE connection fails
• No Stompy tools appear in Claude Desktop

Why this happens

The claude_desktop_config.json file has incorrect syntax, is in the wrong location, or your bearer token is invalid.

Solution

Example

{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Symptoms

• Claude Desktop shows config error on startup
• MCP servers fail to load
• JSON parse error in logs

Why this happens

The claude_desktop_config.json file contains invalid JSON syntax such as trailing commas, missing quotes, or mismatched brackets.

Solution

Example

// WRONG - has trailing comma
{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer token",  // <- Remove this comma!
      }
    }
  }
}

// CORRECT
{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Symptoms

• Connection to Stompy server failed
• SSE endpoint unreachable
• Network error when connecting

Why this happens

The SSE connection to Stompy servers cannot be established. This may be due to network issues, firewall restrictions, or server maintenance.

Solution

Example

{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Symptoms

• Unauthorized error when using Stompy tools
• Token expired or invalid
• Authentication failed
• 401 or 403 errors

Why this happens

Your Stompy bearer token is missing, expired, or incorrectly configured in the Authorization header.

Solution

Symptoms

• New user, tools not working
• Unsure if setup is correct
• Want to verify installation

Why this happens

First-time setup requires several steps to be completed in the correct order.

Solution

Example

{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Symptoms

• One MCP server works but not others
• Tools from different servers mixed up
• Intermittent connection issues

Why this happens

When running multiple MCP servers, they may have conflicting tool names or resource contention.

Solution

Symptoms

• Unsure where to add bearer token
• Token not being recognized
• Need to configure authentication

Why this happens

Stompy uses bearer token authentication in the HTTP headers of the SSE connection.

Solution

Symptoms

• Features not working as documented
• Unexpected tool behavior
• New parameters or options available

Why this happens

Stompy is a hosted service that receives regular updates. New features or changes may affect tool behavior.

Solution

Symptoms

• recall_context returns "not found"
• Context exists but cannot be retrieved
• Topic name not recognized

Why this happens

The topic name does not exist, has a typo, or you are looking in the wrong project.

Solution

Example

// Find all contexts in current project
context_explore()

// Search for contexts about authentication
context_search("authentication")

// Recall with exact topic name
recall_context("auth-api-rules")

Symptoms

• lock_context fails with "novelty" error
• Content rejected as redundant
• "Delta evaluation: <10% novelty" message

Why this happens

Stompy prevents storing duplicate content. If your new context is more than 90% similar to existing contexts, it will be rejected to prevent clutter.

Solution

Example

// Check what similar content exists
context_search("API authentication rules")

// If updating, just lock with same topic (creates new version)
lock_context(
  content="Updated auth rules...",
  topic="auth-rules"  // Same topic = new version
)

// Force store if intentionally similar
lock_context(
  content="Similar but distinct content...",
  topic="auth-rules-v2",
  force_store=True
)

Symptoms

• Need older version of context
• Want to see version history
• Accidentally overwrote content

Why this happens

Contexts are versioned (1.0, 1.1, etc.) and you may need to access a specific version rather than the latest.

Solution

Example

// Get latest version
recall_context("api-spec")

// Get original version
recall_context("api-spec", version="1.0")

// Get specific version
recall_context("api-spec", version="1.2")

Symptoms

• Unsure which priority to use
• Context not appearing in searches
• Critical rules being missed

Why this happens

Stompy has three priority levels that affect how contexts are retrieved and displayed.

Solution

Example

// Critical security rule
lock_context(
  content="NEVER store passwords in plain text",
  topic="security-rules",
  priority="always_check"
)

// Important API documentation
lock_context(
  content="API uses JWT with 15min expiry...",
  topic="api-auth",
  priority="important"
)

// Reference material (default)
lock_context(
  content="Historical context about v1 API...",
  topic="api-v1-history"
  // priority defaults to "reference"
)

Symptoms

• context_search returns empty
• Know content exists but search fails
• Semantic search not finding matches

Why this happens

The search query may not semantically match your content, or you may be searching in the wrong project.

Solution

Example

// Broad semantic search
context_search("authentication")

// Search with tag filter
context_search("api", tags="security")

// Keyword-only search (no semantic)
context_search("JWT token", use_semantic=False)

// Search with priority filter
context_search("rules", priority="always_check")

Symptoms

• Search finds unexpected results
• Exact phrase not matching
• Want literal string matching

Why this happens

By default, context_search uses semantic search (meaning-based) not keyword matching. This finds conceptually related content but may miss exact phrases.

Solution

Example

// Semantic: finds related concepts
context_search("how users log in")
// Might find: "authentication", "JWT tokens", "session management"

// Keyword: exact matching
context_search("JWT", use_semantic=False)
// Only finds contexts containing "JWT"

// Combine with filters for precision
context_search("authentication", priority="important", tags="api")

Symptoms

• unlock_context fails for critical context
• "Requires force=True" error
• Cannot remove always_check priority context

Why this happens

Contexts with priority="always_check" are protected from accidental deletion. This is a safety feature for critical rules.

Solution

Example

// Protected by default - this fails:
unlock_context("security-rules")
// Error: Critical context requires force=True

// Override protection:
unlock_context("security-rules", force=True)
// Archived and deleted

// Alternative: downgrade priority
// (Update the context with lower priority instead)

Symptoms

• Confused about versions
• Want to understand update behavior
• Need to manage context history

Why this happens

Understanding how Stompy versions contexts helps you manage knowledge effectively.

Solution

Example

// Create initial version (v1.0)
lock_context(content="Initial API spec", topic="api-spec")

// Update creates v1.1 (v1.0 still exists)
lock_context(content="Updated API spec", topic="api-spec")

// Recall latest
recall_context("api-spec")  // Gets v1.1

// Recall original
recall_context("api-spec", version="1.0")  // Gets v1.0

// See all versions
db_query("SELECT version, created_at FROM context_locks WHERE label = 'api-spec'")

Symptoms

• "File exceeds 10MB limit" error
• Large file upload fails
• Cannot ingest PDF/image

Why this happens

Stompy has a 10MB file size limit for document ingestion to ensure reasonable processing times and storage costs.

Solution

Symptoms

• "Unsupported file type" error
• File format not recognized
• Extension not supported

Why this happens

Stompy supports specific file types for ingestion. Unsupported formats cannot be processed.

Solution

Symptoms

• Image uploaded but no description generated
• Vision API errors
• Image content not searchable

Why this happens

Image analysis requires the OpenRouter Vision API. If not configured or unavailable, images are stored but not analyzed.

Solution

Symptoms

• "S3 upload failed" error
• Document not stored
• Storage service unavailable

Why this happens

The S3/DigitalOcean Spaces storage service is temporarily unavailable or there are credential issues.

Solution

Symptoms

• "Embedding generation failed" error
• Document stored but not searchable
• VoyageAI errors

Why this happens

Text embeddings are generated by VoyageAI. If the service is unavailable, documents may be stored without embeddings.

Solution

Symptoms

• db_query rejects INSERT/UPDATE/DELETE
• "Write operation not allowed" error
• Need to modify data directly

Why this happens

db_query is read-only by design. For write operations, use db_execute with proper safety confirmations.

Solution

Example

// Read operation - use db_query
db_query("SELECT label, priority FROM context_locks")

// Write operation - use db_execute
db_execute(
  sql="UPDATE context_locks SET priority = %s WHERE label = %s",
  params=["reference", "old-topic"],
  confirm=True
)

Symptoms

• db_execute shows changes but nothing happens
• Dry run works but actual update fails
• "Unconfirmed operation" message

Why this happens

db_execute has safety controls: dry_run=True (default) only previews changes, and confirm=True is required to execute.

Solution

Example

// Step 1: Preview changes (safe)
db_execute(
  sql="DELETE FROM workspace_temp WHERE created_at < '2024-01-01'",
  dry_run=True  // Default - just shows what would happen
)
// Output: "Would affect 15 rows"

// Step 2: Execute for real
db_execute(
  sql="DELETE FROM workspace_temp WHERE created_at < '2024-01-01'",
  dry_run=False,
  confirm=True
)
// Output: "Deleted 15 rows"

Symptoms

• db_schema shows no tables
• Cannot see database structure
• Schema appears empty

Why this happens

You may be looking at the wrong project schema, or the project has not been initialized with any data yet.

Solution

Example

// List all tables in current project
db_schema()

// Get details for specific table
db_schema(table="context_locks")

// Query table structure directly
db_query("SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'context_locks'")

Symptoms

• Cannot create workspace table
• Workspace table not found
• Permission denied for table operations

Why this happens

Workspace tables are temporary tables for complex queries. They have specific naming conventions and lifecycle.

Solution

Example

// Create temp table for analysis
db_workspace(
  operation="create",
  table_name="search_results",
  schema="context_id INTEGER, score REAL, label TEXT",
  confirm=True
)

// Use in queries
db_execute(
  "INSERT INTO workspace_search_results SELECT id, 0.95, label FROM context_locks",
  confirm=True
)

// Clean up
db_workspace(operation="drop", table_name="search_results", confirm=True)

Symptoms

• Query takes too long
• Operation timed out
• Large result set issues

Why this happens

Complex queries or large result sets can exceed timeout limits. db_query auto-adds LIMIT 100 for safety.

Solution

Example

// Efficient: select specific columns with filter
db_query(
  "SELECT label, priority, version FROM context_locks WHERE priority = %s",
  params=["important"]
)

// Paginate large results
db_query("SELECT * FROM context_locks LIMIT 50")
db_query("SELECT * FROM context_locks LIMIT 50 OFFSET 50")

Symptoms

• Contexts from wrong project appearing
• Confused about project boundaries
• Want to understand data separation

Why this happens

Each Stompy project is a completely isolated PostgreSQL schema. Understanding this helps manage multiple projects effectively.

Solution

Example

// See all projects
project_list()

// Switch to specific project
project_switch("client-acme")

// All operations now scoped to client-acme
lock_context(content="Acme API spec", topic="api")
// This context only exists in client-acme project

// Switch to different project
project_switch("personal-blog")
// Cannot see client-acme contexts here

Symptoms

• project_switch seems to fail
• Still seeing old project data
• Handover not loading

Why this happens

Project switching should be instant, but there may be caching or the project name may be incorrect.

Solution

Example

// List available projects
project_list()

// Switch with handover (default)
project_switch("my-project")

// Switch without loading previous session
project_switch("my-project", load_handover=False)

// Create if doesn't exist
project_create("new-project")
project_switch("new-project")

Symptoms

• Previous session context missing
• Handover shows empty
• "No handover available" message

Why this happens

Handover summaries are created at session end. If no previous session exists or it was empty, there may be no handover to load.

Solution

Symptoms

• project_delete fails
• "Requires confirmation" error
• Project deletion blocked

Why this happens

Project deletion is destructive and requires explicit confirmation to prevent accidental data loss.

Solution

Example

// First, review what will be deleted
project_info("old-project")

// Optional: backup first
export_project(output_path="/tmp/old-project-backup.json.gz")

// Delete with explicit confirmation
project_delete("old-project", confirm=True)

// Verify deletion
project_list()

Symptoms

• Embedding generation fails
• Semantic search not working
• VoyageAI API errors

Why this happens

VoyageAI provides embeddings for semantic search. Service outages or rate limits can cause temporary failures.

Solution

Symptoms

• Image analysis fails
• No description generated for images
• Vision API timeout

Why this happens

OpenRouter provides AI vision for image analysis. This is optional - images work without it.

Solution

Symptoms

• context_summarize fails
• "Ollama not available" error
• AI summary not generating

Why this happens

context_summarize uses a local Ollama LLM for privacy-preserving summaries. Ollama must be running locally.

Solution

Example

// Requires Ollama running locally
context_summarize("api-specification")

// Alternative without Ollama:
recall_context("api-specification", preview_only=True)
// Returns 500-char preview instead of AI summary

Symptoms

• Document upload fails
• S3 authentication error
• Cannot store files

Why this happens

Document storage requires S3/DigitalOcean Spaces credentials. This is typically configured server-side.

Solution

Symptoms

• context_search takes too long
• Search feels slow
• Timeout on large projects

Why this happens

Semantic search requires embedding comparison across all contexts. Large projects may take longer.

Solution

Example

// Fast: filtered search
context_search("api", priority="always_check", limit=3)

// Fast: keyword only
context_search("auth-rules", use_semantic=False)

// Slower: broad semantic search
context_search("how does authentication work")

Symptoms

• lock_context times out
• Large content fails to store
• Operation exceeds time limit

Why this happens

Very large contexts take longer to process (embedding generation, storage). Consider chunking or using lazy embedding.

Solution

Example

// Defer embedding for large content
lock_context(
  content="Very long technical specification...",
  topic="full-spec",
  lazy=True  // Embedding generated on first search
)

// Better: split into logical chunks
lock_context(content="Overview...", topic="spec-overview")
lock_context(content="API details...", topic="spec-api")
lock_context(content="Data models...", topic="spec-models")

Symptoms

• sync_project_memory fails
• Background sync not completing
• Project analysis incomplete

Why this happens

Project sync analyzes your entire codebase which can be resource-intensive. Large projects may need multiple runs.

Solution

Example

// Preview changes first
sync_project_memory(dry_run=True)

// Sync critical items only
sync_project_memory(
  priorities=["always_check", "important"],
  confirm=True
)

// Force re-sync
sync_project_memory(force=True, confirm=True)

// Manual trigger for all projects
trigger_background_sync(active_hours=24)