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/mcp
   

"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: memory(action="recall", query="...")
2. Use broader search terms
3. Check if memory was superseded by a correction
4. Verify with system(action="stats") to see memory count

"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. Search across everything: memory(action="recall", query="...", include="all")

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: skill(action="list", id="...")
2. If draft, approve it: skill(action="update", id="...", status="active")
3. Update triggers to match your context

"Can't approve skill"

Symptoms: Approval fails

Solutions:

1. Check pending skills: skill(action="list", status="draft")
2. Verify skill ID is correct
3. System skills cannot be modified — they're read-only

Custom Tool Issues

"Tool execution failed"

Symptoms: Custom tool returns error

Solutions:

1. Test the tool: tool(action="test", tool_id="...", test_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: connection(action="get_token", connection_id="...")
2. Verify API key/token hasn't expired
3. For OAuth2 connections, re-authorize: connection(action="authorize", connection_id="...")
4. 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

"handler.fetch is not a function"

Symptoms: Code tool fails immediately

Cause: Wrong export format.

Fix: Use the Workers module format:

// Correct
export default {
  async fetch(request) {
    const input = await request.json();
    return Response.json({ result: "ok" });
  }
};

// Wrong — causes this error
export default async function(input) { ... }

"Execution timeout"

Symptoms: Code takes too long

Solutions:

1. Optimize code
2. Increase timeout_ms when creating tool (max 300000)
3. Break into smaller operations

"Fetch failed: domain not allowed"

Symptoms: Code can't make HTTP request

Solutions:

1. Add domain to allowed_domains in code_config
2. Update tool: tool(action="update", tool_id="...", code_config={..., allowed_domains: ["api.example.com"]})

"query() returns unexpected results"

Symptoms: Database queries return undefined or wrong data

Common pitfalls:

// Wrong: params as array
await query("SELECT * FROM t WHERE a = ? AND b = ?", [val1, val2]);
// Fix: spread params
await query("SELECT * FROM t WHERE a = ? AND b = ?", val1, val2);

// Wrong: direct indexing
const row = (await query("SELECT * FROM t"))[0];
// Fix: access .rows
const row = (await query("SELECT * FROM t")).rows[0];

"eval() / new Function() blocked"

Symptoms: Code fails with security error

Cause: Dynamic code evaluation is blocked in the sandbox.

Fix: Restructure code to avoid eval/new Function. Use static logic instead.

Connection Issues (API Connections)

"Secret URL not working"

Symptoms: Browser link for credential entry doesn't load or doesn't save

Solutions:

1. Generate a new URL: connection(action="secret_url", connection_id="...")
2. URLs are single-use — if already used, generate a new one
3. Check connection still exists: connection(action="list")

"OAuth2 authorization fails"

Symptoms: OAuth flow doesn't complete

Solutions:

1. Ensure redirect URI is correct (dynamic based on host)
2. Check provider credentials (client ID/secret)
3. Verify OAuth scopes are valid for the provider
4. Try again: connection(action="authorize", connection_id="...")

"Connection env vars not available in code tool"

Symptoms: process.env.KYEW_CONN_* is undefined

Solutions:

1. Verify connection_ids includes the connection ID in code_config
2. Check connection name — env var uses uppercased name with non-alphanumeric → underscores
3. Verify connection has active credentials: connection(action="get_token", connection_id="...")

Scheduling Issues

"Scheduled tool not running"

Symptoms: Tool doesn't execute at scheduled time

Solutions:

1. Verify tool is active (not draft): tool(action="get", tool_id="...")
2. Check schedule is enabled: tool(action="schedule", schedule_action="list")
3. Verify timezone is correct — hours are in local time
4. Check if auto-paused after 3 failures: tool(action="schedule", schedule_action="history", tool_id="...")
5. Re-enable: tool(action="schedule", tool_id="...", schedule={enabled: true})

"Email summaries not arriving"

Symptoms: Tool runs but no email

Solutions:

1. Verify email_summary is enabled in schedule
2. Check email_address is correct (defaults to account email)
3. Check spam folder
4. Review run history for errors: tool(action="schedule", schedule_action="history", tool_id="...")

Remote MCP Issues

"Remote server tools not available"

Symptoms: Added a server but can't use its tools

Solutions:

1. Check server status: mcp(action="list")
2. Refresh tools: mcp(action="refresh", server_id="...")
3. Use gateway tool to discover: {tool_prefix}(action="tools")
4. Verify server URL is correct and reachable

"Gateway tool call fails"

Symptoms: Calling a remote tool returns error

Solutions:

1. Verify auth is set up if server requires it (connection_id or headers)
2. Check tool name matches exactly: {tool_prefix}(action="search", query="...")
3. Remote server may be down — check its status independently

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. Report an issue: system(action="feedback", title="...", description="...")
3. Try disconnecting and reconnecting
4. Check the Kyew discovery tool: kyew(action="help")