Agent Issues Troubleshooting

This guide covers common problems with Zenmako agents and chat functionality, along with solutions to resolve them.

Agent Not Responding

Symptoms

  • Chat interface shows no response after sending a message
  • Loading indicator spins indefinitely
  • No error message displayed

    • Possible Causes and Solutions

    Network or Connection Issues
  • Check your internet connection by loading another website
  • Look for network errors in your browser's developer console (F12 > Console tab)
  • If using a VPN, try disconnecting temporarily to rule out routing issues
    • Service Temporarily Unavailable
  • Check the Zenmako status page for any ongoing incidents
  • Wait 2-3 minutes and try again
  • If the issue persists, the AI service may be experiencing high load
    • What to Do
  • Refresh the page using Ctrl+R (Windows/Linux) or Cmd+R (Mac)
  • Wait 30 seconds and retry your message
  • If the problem continues, try logging out and back in
  • Clear your browser cache and cookies for the Zenmako domain

    • Slow Responses

    Symptoms

  • Agent takes more than 30 seconds to respond
  • Partial responses appear very slowly
  • Interface feels unresponsive during queries

    • Possible Causes and Solutions

    Complex Queries Take Longer Solution: Break complex requests into smaller, focused questions. Multiple Tool Calls

    When an agent needs to call external tools (like fetching data from connected services), each call adds latency.

    Solution:
  • Be specific about what data you need
  • Limit the scope of your request when possible
  • If you only need data from one integration, mention it explicitly
    • Large Data Processing

    Processing large files, extensive search results, or bulk data operations takes additional time.

    Solution:
  • Filter your requests to specific date ranges or categories
  • Request summaries instead of full data dumps
  • Upload smaller files when possible

    • Wrong or Unexpected Answers

    Symptoms

  • Agent provides outdated information
  • Responses do not match what you asked
  • Agent seems confused about context

    • Possible Causes and Solutions

    Knowledge Base Outdated

    The agent may be working with stale information from your connected integrations.

    Solution:
  • Trigger a manual sync for the relevant integration (Settings > Integrations > Sync)
  • Verify the data is current in the source system
  • Ask the agent to fetch fresh data explicitly: "Get the latest data from [source]"
    • Question Too Vague

    Ambiguous questions lead to unpredictable answers.

    Solution: Be specific in your requests:
    Instead of...Try...
    "What are the tasks?""What are my open tasks in Asana for Project X?"
    "Show me the data""Show me sales data from Salesforce for Q4 2025"
    "Find the document""Find the document titled 'Q1 Planning' in Google Drive"
    Missing Context

    The agent may not have enough information to answer correctly.

    Solution:
  • Provide relevant background in your question
  • Reference specific projects, files, or records by name
  • If following up on a previous topic, summarize what was discussed
    • How to Improve Your Questions
  • State the integration or data source explicitly
  • Include relevant identifiers (project names, ticket numbers, etc.)
  • Specify the format you want (list, summary, detailed breakdown)
  • Mention any constraints (date range, status, category)

    • Tool Calls Failing

    Symptoms

  • Error messages mentioning specific integrations
  • "Failed to execute action" errors
  • Agent reports it cannot access certain data

    • Possible Causes and Solutions

    Connection Issues

    The integration may have lost its connection.

    Solution:
  • Go to Settings > Integrations
  • Find the affected integration
  • Check the connection status
  • Reconnect if necessary by clicking "Reconnect" or re-authorizing
    • Permission Denied

    Your account may lack permissions for the requested action.

    Solution:
  • Verify you have the required permissions in the source system
  • Check if the integration's access token has the necessary scopes
  • Reconnect the integration with expanded permissions if needed
  • Contact your workspace admin if permissions were recently changed
    • Resource Not Found

    The requested item may have been deleted, moved, or renamed.

    Solution:
  • Verify the resource exists in the source system
  • Check if the item was recently moved to a different location
  • Use the correct current name or identifier
  • Ensure the integration has access to the relevant project/folder/board

    • For detailed integration troubleshooting, see Connection Issues.

    Token Limit Reached

    Symptoms

  • Message stating you have reached your usage limit
  • Agent refuses to process new requests
  • "Token limit exceeded" or "Rate limit reached" errors

    • What It Means

    Each plan has a monthly token allocation. When exhausted, agent functionality is restricted until the limit resets or you upgrade.

    When Limits Reset

    Check your specific reset date in Settings > Billing > Usage.

    How to Check Usage

  • Navigate to Settings > Billing > Usage
  • View your current token consumption
  • See a breakdown by:
    • - Agent conversations - Tool calls - Document processing

    Upgrading Your Plan

    If you consistently hit token limits:

  • Go to Settings > Billing > Plans
  • Compare available plan options
  • Select a plan with higher token allocation
  • Complete the upgrade process
    • Tips to Reduce Token Usage:
  • Be concise in your questions
  • Avoid repeatedly asking the same questions
  • Use filters to limit data retrieval scope
  • Summarize long documents before uploading

    • Still Having Issues?

    If none of these solutions resolve your problem:

  • Gather relevant details:
    • - Exact error messages - Steps to reproduce - Browser and operating system - Time when the issue occurred
  • Check the FAQ for additional answers
  • Contact support through Settings > Help > Contact Support