Troubleshooting

Solutions to common issues when using Kyew.

Connection Issues

"Authentication failed"

Symptoms: Can't connect, auth errors

Solutions:

1. Clear browser cookies and re-authenticate
2. Ensure popups aren't blocked for OAuth
3. Try a different browser
4. Check that you're using a valid Google account

"Connection refused"

Symptoms: Can't reach server

Solutions:

1. Check internet connection
2. Verify server status at mcp.kyew.ai/health
3. Reconnect:

   claude mcp remove kyew
   claude mcp add kyew --transport http --scope user https://mcp.kyew.ai
   

"Tools not showing up"

Symptoms: Kyew tools not available in Claude

Solutions:

1. Restart Claude Code or Claude Desktop
2. Verify connection: claude mcp list
3. Re-authenticate if session expired

Memory Issues

"Memory not found"

Symptoms: Can't recall a memory you stored

Possible causes:

• Memory was forgotten/deleted
• Searching in wrong domain
• Typo in search query

Solutions:

1. Search without domain filter
2. Use broader search terms
3. Check if memory was superseded by a correction

"Recall returns no results"

Symptoms: Search finds nothing

Solutions:

1. Try simpler search terms
2. Remove domain filter
3. Check that you have memories stored
4. Verify with stats to see memory count

Skill Issues

"Skill not being suggested"

Symptoms: Expected skill isn't recommended

Possible causes:

• Skill is still in draft status
• Skill triggers don't match context
• Skill is deprecated

Solutions:

1. Check skill status: get_skill by name "..."
2. If draft, approve it: approve_skill id "..."
3. Update triggers to match your context

"Can't approve skill"

Symptoms: Approval fails

Possible causes:

• Skill doesn't exist
• Skill is already active
• Skill was rejected

Solutions:

1. Check pending skills: list_skills status "draft"
2. Verify skill ID is correct

Dynamic Tool Issues

"Tool execution failed"

Symptoms: Custom tool returns error

Solutions:

1. Test the tool: test_dynamic_tool id "..." with input {...}
2. Check configuration is correct
3. For HTTP tools, verify connection credentials

"HTTP proxy returns 401/403"

Symptoms: API authentication fails

Solutions:

1. Check connection credentials are correct
2. Verify API key/token hasn't expired
3. Ensure connection uses correct auth type

"Transform expression error"

Symptoms: JSONata evaluation fails

Solutions:

1. Validate JSONata at try.jsonata.org
2. Remember to access input via input.field
3. Use JSONata functions, not JavaScript methods

Code Tool Issues

"Code tool not executing"

Symptoms: Code tool doesn't run

Possible causes:

• Tool not approved
• Syntax error in code
• Timeout

Solutions:

1. Check if tool is approved: list_pending_code_tools
2. Review code for syntax errors
3. Test with smaller input

"Execution timeout"

Symptoms: Code takes too long

Solutions:

1. Optimize code
2. Increase timeout_ms when creating tool
3. Break into smaller operations

"Fetch failed: domain not allowed"

Symptoms: Code can't make HTTP request

Solutions:

1. Add domain to allowed_domains when creating tool
2. Update tool to include the domain

Agent Coordination Issues

"Can't see other agents"

Symptoms: agent_list shows no other agents

Possible causes:

• Other agents haven't sent heartbeat
• Sessions expired
• Different user accounts

Solutions:

1. Ensure all agents send heartbeats regularly
2. Check all agents use same Google account

"Task already claimed"

Symptoms: Can't claim a task

Solutions:

1. Task was claimed by another agent
2. List available tasks: agent_list_tasks status "open"

Rate Limiting

"Rate limited"

Symptoms: 429 error, requests rejected

Solutions:

1. Wait and retry
2. Reduce request frequency
3. Batch operations where possible

Getting Help

If these solutions don't resolve your issue:

1. Check server status: mcp.kyew.ai/health
2. Review logs if available
3. Try disconnecting and reconnecting
4. Report persistent issues with details