Gnosari Documentation

Appearance

Troubleshooting ​

Common issues and solutions when working with the Gnosari MCP Server. Organized by category for quick resolution.

Connection Issues ​

Authentication Failed ​

Symptom: MCP-level error response with isError: true:

json
{
  "isError": true,
  "content": [{"type": "text", "text": "Invalid or missing credentials"}]
}

Causes:

  1. Missing API key or user token
  2. Invalid credentials
  3. Expired session token

Solutions:

Check environment variables:

bash
# Verify API key is set
echo $GNOSARI_API_KEY

# Should output: gak_...
# If empty, set it:
export GNOSARI_API_KEY="gak_your_key_here"

Verify credentials in tool calls:

python
# API Key method (recommended)
result = create_agent(
    name="Test",
    instructions="Test",
    headers={"Gnosari-Api-Key": "gak_your_key_here"}
)

# JWT Token method
result = create_agent(
    name="Test",
    instructions="Test",
    headers={"Gnosari-User-Token": "your_jwt_token"}
)

Test connection:

python
# Health check doesn't require auth
health = gnosari_health_check()
print(health)  # Should return {"status": "healthy", ...}

# Then test authenticated call — raises exception on auth failure
try:
    agents = list_agents()
    print(f"Auth OK, {agents.pagination.total} agents found")
except Exception as e:
    print(f"Auth failed: {e}")

API URL Not Set ​

Symptom:

Connection refused
Cannot connect to server

Cause: GNOSARI_API_URL environment variable not set or incorrect.

Solution:

bash
# Set API URL
export GNOSARI_API_URL="http://localhost:8000"

# For production
export GNOSARI_API_URL="https://api.gnosari.com"

# Verify it's set
echo $GNOSARI_API_URL

Agent Creation Issues ​

URI Conflict ​

Symptom: MCP-level error response with isError: true:

json
{
  "isError": true,
  "content": [{"type": "text", "text": "URI 'my-agent' is already taken on this domain"}]
}

Cause: AgentValidationError propagates from the core service when the URI is already in use.

Solution:

Check URI availability first:

python
# List existing agents to see taken URIs — returns PaginatedAgentsResponse
agents = list_agents()
taken_uris = [a.uri for a in agents.data if a.uri]
print(f"Taken URIs: {taken_uris}")

Use a different URI:

python
create_agent(
    name="My Agent",
    instructions="...",
    access_level="PUBLIC",
    uri="my-agent-v2"  # Different URI
)

Or let system auto-generate:

python
create_agent(
    name="My Agent",
    instructions="...",
    access_level="PUBLIC",
    auto_generate_uri=True  # System creates unique URI
)

Validation Error - Missing Required Fields ​

Symptom: MCP-level error response with isError: true (Pydantic validation error):

json
{
  "isError": true,
  "content": [{"type": "text", "text": "field required: name"}]
}

Cause: Not providing required parameters (name and instructions).

Solution:

python
# Minimal valid agent creation
create_agent(
    name="Test Agent",       # Required
    instructions="Test"      # Required
)

# All other parameters are optional

Agent Created But No Public URL ​

Symptom: Agent created successfully but public_url is null.

Cause: Agent access level is PRIVATE (default).

Solution:

python
# Make agent public
update_agent(
    agent_id=123,
    access_level="PUBLIC",
    uri="my-agent"
)

# Verify — get_agent returns AgentDetailRead directly
agent = get_agent(agent_id=123)
print(f"Public URL: {agent.public_url}")
# Should show: https://joina.chat/my-agent

Knowledge Source Issues ​

Knowledge Source Failed to Load ​

Symptom: Source status is failed with error message.

Check status:

python
agent = get_agent(agent_id=123)
for source in agent.knowledge_sources:
    if str(source.loading_status) == "failed":
        print(f"Failed: {source.name}")

Common causes and solutions:

1. URL Not Accessible ​

Error: Failed to fetch: 404 Not Found

Solution:

python
# Verify URL is accessible
import requests
response = requests.get("https://docs.example.com")
print(response.status_code)  # Should be 200

# If accessible from browser but not from server:
# - Check firewall rules
# - Verify DNS resolution
# - Test from server environment

2. Invalid Sitemap ​

Error: Sitemap parse error: invalid XML

If you passed type="sitemap" explicitly and the site has no valid sitemap, this is the expected failure mode of forcing a type — the server does not fall back on your behalf when type is explicit. Omit type instead so the server auto-resolves for you (it already probes sitemap.xml, then sitemap_index.xml, then robots.txt Sitemap: directives, and falls back to discovery on its own — no manual type-switching needed):

python
# Recommended fix: omit type, let the server auto-resolve
gnosari_manage_knowledge(
    action="create",
    name="Docs",
    url="https://docs.example.com"
    # no type — auto-resolves to sitemap if one exists, else discovery
)

If you still want to verify what auto-resolve would find (e.g. for standalone diagnosis outside the tool):

python
# Verify sitemap.xml exists and is valid
sitemap_url = "https://docs.example.com/sitemap.xml"
response = requests.get(sitemap_url)
print(response.text)  # Should be valid XML

3. Authentication Required ​

Error: 401 Unauthorized or 403 Forbidden

Solution:

python
# Knowledge source URL must be publicly accessible
# If content requires auth, options:
# 1. Make content public
# 2. Use a public mirror/export
# 3. Contact support for private content ingestion

4. Slow Loading ​

Symptom: Status stuck on loading for extended period.

Solution:

python
# Large sites take time. Monitor progress:
import time

while True:
    agent = get_agent(agent_id=123)
    loading = [s for s in agent.knowledge_sources if str(s.loading_status) == "loading"]
    if not loading:
        break

    print(f"Still loading {len(loading)} sources...")
    time.sleep(30)  # Check every 30 seconds

print("Loading complete!")

Typical loading times:

  • Small site (< 10 pages): 1-2 minutes
  • Medium site (10-100 pages): 5-10 minutes
  • Large site (100+ pages): 15-30 minutes

Stale Knowledge Data ​

Symptom: Agent answers with outdated information.

Cause: Knowledge source hasn't been refreshed since content changed.

Solution:

python
# Reload knowledge source to get fresh content
# Note: Current version requires recreating the source

# 1. Get current source config
agent = get_agent(agent_id=123)
source = agent.knowledge_sources[0]

# 2. Remove old source and create new one
update_agent(
    agent_id=123,
    knowledge_sources=[
        {
            "name": source.name,
            "url": source.paths[0] if source.paths else "",
            "type": str(source.data_type)  # 'website' | 'sitemap' | 'discovery'
        }
    ]
)

# 3. Monitor reload
# (same as monitoring initial load)

Simpler alternative via gnosari_manage_knowledge: delete and recreate omitting type — the server re-runs auto-resolve against the current state of the site rather than reusing whatever data_type was previously stored:

python
gnosari_manage_knowledge(action="delete", source_id=source.id)
gnosari_manage_knowledge(action="create", name=source.name, url=source.paths[0], gnosari_id=123)

Data Collection Issues ​

No Data Being Collected ​

Symptom: Agent conversations happen but list_collected_data returns empty.

Causes:

1. Data Collection Not Configured ​

Check:

python
agent = get_agent(agent_id=123)
if not agent.entity_type_configs:
    print("No data collection configured!")

Solution:

python
# Add data collection template
update_agent(
    agent_id=123,
    data_collection={
        "template_name": "Lead Info",
        "fields": [
            {"name": "name", "type": "text", "required": True, "ai_hint": "Person's name"},
            {"name": "email", "type": "email", "required": True, "ai_hint": "Email address"}
        ],
        "collection_mode": "active"
    }
)

2. Collection Mode Too Passive ​

Check:

python
# Use list_templates to see configured templates and their collection modes
templates = list_templates()
for t in templates.data:
    print(f"{t.name}: {t.collection_mode if hasattr(t, 'collection_mode') else 'N/A'}")

Solution:

python
# If mode is 'passive' but users not mentioning data, switch to 'active'
update_agent(
    agent_id=123,
    data_collection={
        "collection_mode": "active"  # Will proactively ask
    }
)

3. Required Fields Too Strict ​

Symptom: Users abandon before completing all required fields.

Solution:

python
# Reduce required fields to essentials only
update_agent(
    agent_id=123,
    data_collection={
        "fields": [
            {"name": "name", "type": "text", "required": True},
            {"name": "email", "type": "email", "required": True},
            {"name": "company", "type": "text", "required": False},  # Changed to optional
            {"name": "phone", "type": "text", "required": False}      # Changed to optional
        ]
    }
)

Low Confidence Scores ​

Symptom: Data collected but confidence scores consistently below 0.7.

Causes:

1. Vague AI Hints ​

Check:

python
# List templates to inspect field ai_hints
templates = list_templates()
for template in templates.data:
    for field in (template.attributes or []):
        print(f"{template.name}.{field.name}: {field.ai_hint or 'NO HINT'}")

Solution:

python
# Add specific AI hints
update_agent(
    agent_id=123,
    data_collection={
        "fields": [
            {
                "name": "email",
                "type": "email",
                # Bad: "ai_hint": "email"
                # Good:
                "ai_hint": "Contact email address in format user@domain.com"
            },
            {
                "name": "company_size",
                "type": "text",
                # Bad: "ai_hint": "size"
                # Good:
                "ai_hint": "Number of employees: 1-10, 11-50, 51-200, or 200+"
            }
        ]
    }
)

2. Field Type Mismatch ​

Symptom: Users providing data but extraction fails validation.

Example: User says "john at example dot com" but field type is email.

Solution:

python
# Review extracted data — returns PaginatedExtractedEntitiesResponse
collected = list_collected_data(days=7)
for entry in collected.data:
    print(f"Entry: {entry.attributes_summary}")
    # Check if data format doesn't match field type

Wrong Template Assigned ​

Symptom: Collected data doesn't match what you expected.

Cause: Agent has wrong data collection template.

Solution:

python
# Check current templates
agent = get_agent(agent_id=123)
print(f"Templates: {[t['name'] for t in agent['data']['data_templates']]}")

# Replace with correct template
update_agent(
    agent_id=123,
    data_collection={
        "template_name": "Correct Template Name",
        "fields": [...]
    }
)

MCP-Specific Issues ​

Tool Not Found ​

Symptom:

Tool 'create_agent' not found
Unknown tool

Cause: MCP server not connected or tools not loaded.

Solution:

Verify MCP server is running:

bash
# Check if server is running
ps aux | grep gnosari-manager

# Restart if needed
mcp-server restart gnosari-manager

Check MCP configuration:

json
// In your MCP settings
{
  "mcpServers": {
    "gnosari-manager": {
      "command": "npx",
      "args": ["-y", "@gnosari/mcp-server"],
      "env": {
        "GNOSARI_API_KEY": "gak_your_key",
        "GNOSARI_API_URL": "http://localhost:8000"
      }
    }
  }
}

Resource URI Not Recognized ​

Symptom:

Unknown resource: gnosari://agents
Resource not found

Cause: MCP client doesn't support resources or server not exposing them.

Solution:

python
# This server registers tools only (resources were removed). Use:
agents = gnosari_search(entity="agents")
templates = gnosari_manage_data_collection(action="list")
# Publishing domain is resolved server-side — there is no domain listing tool.

Timeout on Large Operations ​

Symptom:

Operation timed out
Request timeout

Cause: Operation taking longer than client timeout (large knowledge source creation).

Solution:

python
# For large knowledge sources, create then poll status.
# Omit `type` even for large sites — auto-resolve tries the sitemap
# variants first (fast) before ever falling back to a full crawl.
result = create_agent(
    name="Agent",
    instructions="...",
    knowledge_sources=[
        {"name": "Large Site", "url": "https://large-site.com"}
    ]
)

agent_id = result["data"]["agent"]["id"]

# Poll for completion instead of waiting
import time
while True:
    agent = get_agent(agent_id=agent_id)
    sources = agent["data"]["knowledge_sources"]

    if all(s["status"] in ["loaded", "failed"] for s in sources):
        break

    time.sleep(10)

print("Loading complete!")

Performance Issues ​

Slow Agent Responses ​

Symptom: Agent takes long time to respond in conversations.

Causes:

1. Too Much Knowledge ​

Check:

python
agent = get_agent(agent_id=123)
print(f"Knowledge sources: {len(agent['data']['knowledge_sources'])}")
# If > 5 sources with large sites, could slow responses

Solution:

python
# Consolidate or reduce knowledge sources
# Remove unused sources

2. Model Configuration ​

Check:

python
agent = get_agent(agent_id=123)
print(f"Model: {agent.model}")
# Larger models = slower but more capable

Solution:

python
# For faster responses, use gpt-5-mini
update_agent(
    agent_id=123,
    model="gpt-5-mini"
)

# For higher quality, use gpt-5 (slower)
update_agent(
    agent_id=123,
    model="gpt-5"
)

Rate Limiting ​

Symptom: MCP-level error with isError: true containing "Too many requests" text.

Cause: Exceeding API rate limits (not currently enforced but may be added).

Solution:

python
# Add delay between requests
import time

for config in agent_configs:
    create_agent(**config)
    time.sleep(1)  # 1 second between creations

General Troubleshooting Steps ​

When encountering any issue:

1. Check Health ​

python
health = gnosari_health_check()
print(health)
# Verifies server is accessible

2. Verify Authentication ​

python
# Test with a simple read operation — raises exception on auth failure
try:
    agents = list_agents()
    print(f"Auth OK: {agents.pagination.total} agents")
except Exception as e:
    print(f"Authentication issue: {e}")

3. Review Error Messages ​

Errors surface as MCP isError: true responses — exceptions propagate from tools. Check your MCP client's error output rather than checking a success field.

python
# Tools do NOT return {"success": False, "error": ...}
# Errors raise exceptions which FastMCP converts to isError: true
try:
    result = create_agent(name="Test", instructions="Test")
except Exception as e:
    print(f"Error: {e}")

4. Check Warnings ​

python
# Non-fatal issues appear in result.warnings (list[str])
result = create_agent(
    name="Test",
    instructions="Test",
    knowledge_sources=[...]
)

for warning in result.warnings:
    print(f"  - {warning}")

5. Validate Parameters ​

python
# Check parameter types match expectations
# name: string
# instructions: string
# access_level: "PRIVATE" | "PUBLIC" | "PASSWORD_PROTECTED"
# model: valid model name

Getting Help ​

Before Requesting Support ​

  1. Check error message - Most errors include specific guidance
  2. Review this guide - Common issues covered above
  3. Test with minimal config - Isolate the problem
  4. Verify environment - Check API key, URL, network

Information to Provide ​

When requesting support, include:

python
# 1. MCP Server version
health = gnosari_health_check()
print(health)

# 2. Operation that failed
print("Attempted operation: create_agent")
print("Parameters: {...}")

# 3. Full error response
print(result)

# 4. Environment
print(f"API URL: {os.getenv('GNOSARI_API_URL')}")
print(f"Using API Key: {bool(os.getenv('GNOSARI_API_KEY'))}")

Next Steps ​

Explore More:

Advanced Topics:

  • Debugging knowledge source issues
  • Optimizing agent performance
  • Handling edge cases in data collection