Skip to content

Troubleshooting

Common issues and solutions for using the LexSocket MCP servers.

Authentication Issues

"Invalid or expired authentication credentials" (401)

Your authentication token has expired or is invalid.

Solutions:

  1. If using OAuth (Claude Desktop/Code):
  2. Restart the MCP client
  3. The client will automatically refresh the OAuth token on next use

  4. If the problem persists, log out and log back in through the OAuth prompt

  5. If using API Key:

  6. Verify the key is correct: echo $LEXSOCKET_API_KEY
  7. Check that the key hasn't been revoked in the LexSocket Dashboard
  8. Generate a new key: LexSocket Dashboard → Dashboard → Create key

  9. Verify the header is correctly formatted: x-api-key: sk-... (no extra spaces)

  10. If using Le Chat or Cherry Studio:

  11. Verify the API key is included in headers
  12. Check that you're using the correct MCP endpoint: https://mcp.lexsocket.ai/

"Connection refused" or "Failed to connect"

The MCP server is unreachable.

Solutions:

  1. Verify the endpoint URL:
  2. Should be: https://mcp.lexsocket.ai/

  3. NOT the old separate URLs (eurlex.lexsocket.ai, ted.lexsocket.ai, etc.)

  4. Check internet connectivity: 

    curl https://mcp.lexsocket.ai/status
    Should return a 200 status.

  5. If running locally with AUTH_ENABLED=false:

  6. Verify server is running: cd src/mcp && AUTH_ENABLED=false python -m src.main
  7. Check the console for errors

  8. Default local URL: http://localhost:5000

  9. Firewall/proxy issues:

  10. Ensure port 443 (HTTPS) is open
  11. If behind a corporate proxy, configure your MCP client to use it

Rate Limiting

"Rate limit exceeded: 60 requests per minute"

You've exceeded the rate limit for your tier.

Solutions:

  1. Check remaining quota:
  2. Response headers include: X-RateLimit-Remaining: 42

  3. Wait for the window to reset (typically 1 minute)

  4. Implement backoff retry logic: 

    import time

def search_with_retry(query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return search_ted(query)
        except RateLimitError as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # 1s, 2s, 4s
                time.sleep(wait_time)
            else:
                raise

  5. Batch requests efficiently:

  6. Reduce frequency of requests
  7. Cache results locally

  8. Use limit parameter to get more results per request (up to 100)

  9. Contact support for higher limits:

  10. Email: support@lexsocket.ai
  11. Include your use case and required request rate

Search Issues

"No results found" for a query that should return results

Your search query didn't match any tenders.

Debugging steps:

  1. Check your country code:
  2. TED supports all EU/EEA countries (use ISO 3166-1 alpha-3 codes: FRA, DEU, POL)
  3. National Tenders only covers: FR, GB, DE, ES, IT, NL, IE, PT, DK, PL, AT

  4. Example: Use FRA not FR for TED

  5. Try a simpler query: 

    {
    "method": "search_ted",
    "params": {
        "query": "construction",
        "limit": 10
    }
}
    If this returns results but your specific query doesn't, your keywords may not match any tenders.

  6. Try semantic search instead of FTS: 

    {
    "method": "search_ted_semantic",
    "params": {
        "query": "We build hospitals and clinics",
        "limit": 10
    }
}

  7. Check date filters:

  8. Verify published_after / deadline_after aren't too restrictive

  9. Try removing date filters to see if results exist

  10. Verify the CPV code:

  11. Use a broader code: 72 instead of 72101000

  12. Check the European Commission CPV database

  13. Search without filters:

  14. Remove country, CPV, value range filters
  15. Gradually add filters back to isolate the issue

Query returns different results each time

Slight ranking variations are normal due to the hybrid search algorithm.

Expected behavior: - Hybrid search uses Reciprocal Rank Fusion (RRF) to combine FTS and vector results - Small changes in ranking between queries are normal - Top results should be consistent

To reduce variance: - Use mode: "fts" for exact keyword matching (deterministic) - Avoid overly broad queries

"No results found" for a valid CPV or NUTS code

The code may be valid but no tenders match your filters.

Solutions:

  1. Verify the code exists:
  2. CPV codes: Check SIMAP CPV database

  3. NUTS codes: Check Eurostat NUTS

  4. Try without other filters: 

    {
    "method": "search_ted_by_cpv",
    "params": {
        "cpv_code": "72000000"
    }
}

  5. Use broader CPV codes:

  6. Instead of 72101000, try 72100000 or 72000000

  7. Check data freshness:

  8. TED data updates twice daily
  9. National tenders update daily
  10. Recent tenders may not be indexed yet

Local Development Issues

"ModuleNotFoundError: No module named 'tantivy'"

The Tantivy library (full-text search) is not installed.

Solution: 

pip install tantivy

If using a virtual environment: 

source venv/bin/activate
pip install tantivy

"Error: GCS authentication failed"

Running index pipelines locally without GCS credentials.

Solution:

  1. Set up GCS credentials: 

    export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

  2. Or disable GCS sync for local dev: 

    cd src/ted/index
python pipeline.py --db-path ted_notices.db --skip-export

  3. For National Tenders local embedding: 

    cd src/national_tenders/index
python embed.py  # Uses local BGE-M3 ONNX by default

Server fails to start: "Address already in use"

Port is occupied by another process.

Solutions:

  1. Find and kill the process: 

    lsof -i :5000  # Find process on port 5000
kill -9 <PID>

  2. Or use a different port: 

    PORT=5001 python -m src.main

  3. Or restart your system to free all ports.

Data & Freshness Issues

"Why is the tender I just published not in the database?"

TED and National Tenders update on schedules, not in real-time.

Update schedule:

Source Frequency Latency
TED Twice daily (06:00, 18:00 UTC) 2-4 hours from publication
National Tenders Daily per country (01:00-04:45 UTC) Same-day to next-day

Solutions: - Wait for the next scheduled update - Check directly on the source website (TED.europa.eu, BOAMP, Contracts Finder, etc.)

"The statistics show different numbers than the platform says"

Data may be partially processed or a sync is in progress.

Explanations: - Index rebuild is weekly (Sunday 03:00 UTC for TED, 06:00 UTC for National Tenders) - During rebuilds, statistics may temporarily differ - De-duplicated records may differ from raw platform counts

Solution: Check back after the weekly rebuild completes.

Tenders showing as "active" but deadline has passed

Status data may lag behind the actual deadline.

Explanation: - Status is updated daily during collection - Platform status may be ahead of LexSocket - "Active" status reflects the last known state

Solution: Always verify deadline directly on the source platform before submitting a bid.

Error Codes Reference

Common HTTP Status Codes

Code Meaning Action
200 Success None, check response body
400 Bad parameter Review your parameters (country code, CPV, dates)
401 Auth failed Re-authenticate or check API key
429 Rate limited Implement backoff retry; wait 1-2 minutes
500 Server error Retry after 5-30 seconds

Still Stuck?

Contact Support

When reporting issues, include:

  1. What you were trying to do (the query, the tool)
  2. The exact error message (with status code if applicable)
  3. Your steps to reproduce the issue
  4. What you expected to happen
  5. Country/region you're searching (if relevant)
  6. Client and version (Claude Desktop 0.x, Le Chat, etc.)

Next Steps