Skip to content
Nappai Documentation

Troubleshooting

This guide is your first point of reference when something isn’t working as expected. Here we cover the most common errors and teach you how to interpret logs to find the solution.

Common Component Errors

Problems with API Request

When an API Request component fails, it is usually not a NappAI error, but rather an error response from the external service you are querying.

  • How to Diagnose: The first step is always to inspect the node’s output. The API Request component will provide the status code and the exact error message returned by the external API as its output.
  • Interpreting Error Codes: Although every API has its own documentation, most follow a standard:
    • 5xx Errors (e.g., 500, 503): These indicate an internal server error on the API you are querying. The problem is not in your configuration but in the external service.
    • 4xx Errors (e.g., 401, 403, 404): Generally these are access or authorization issues. Check that your API Key or Bearer Token is correct and that you have permission to access that resource. A 404 Not Found means the URL (endpoint) is incorrect.
    • 3xx Errors (e.g., 301, 302): These indicate redirections. The API is telling you that the resource you are looking for has moved to a new URL.

Golden Rule: To understand an API error in depth, the official documentation of that API is always the definitive source of truth.

Common Issues with Agents

Agents are powerful, but debugging them requires understanding their “thought process.”

  • The Agent stays “thinking” (Timeout):

    • Cause: The Agent is trying to solve a very complex task, or the tool it called (e.g., an external API) is taking too long to respond.
    • Solution: Increase the Max Iterations in the Agent’s advanced settings. If the problem persists, simplify the System Prompt or review the performance of the tools it uses.

  • The Agent does not use the correct tool:

    • Cause: The tool description (Tool Description) is not clear enough. The Agent decides which tool to use based solely on that description.
    • Solution: Rewrite the description to be very explicit. Instead of “Manage Airtable,” write “Use this tool to READ records from the Products table. It cannot write or delete.”

  • The Agent returns a result in the wrong format:

    • Cause: The System Prompt is not strict enough.
    • Solution: Add explicit rules to the prompt. For example: ALWAYS respond with a JSON object. Do not add introductory text. The JSON must have the keys "name" and "email".

The Agent “Hallucinates,” Loses the Thread, or Takes Too Long

This is one of the most common problems when designing complex agents and is usually due to information or context saturation.

  • The Root Cause: A single Agent assigned too many tasks, connected to too many tools, or asked to process a massive amount of data in a single interaction can become overloaded.

    • Memory Saturation: The Agent depends on temporary memory to know what it has done and what it still needs to do. With too many tasks, it can “lose the thread” and fail to complete the process correctly.
    • LLM Context Excess: Every tool, instruction, and piece of data is sent to the underlying Language Model (LLM). A massive context not only drastically increases token costs but can also confuse the model, causing it to ignore instructions, take too long to respond, or generate “hallucinations” (incorrect answers).

  • The Solution: Multi-Agent Architectures Instead of creating a single “super-agent” that does everything, the most robust, efficient, and economical strategy is to divide the work among a team of specialized agents.

    • Lower Costs and Higher Efficiency: Sending data incrementally to smaller, focused agents is much cheaper and faster than sending a huge block of information to a single LLM.
    • Greater Reliability: Each agent has a single clear task, drastically reducing the chance of “losing the thread.”
    • Use of Cheaper Models: A simple, well-defined task can often be solved by a smaller, cheaper model, reserving powerful models only for tasks that truly require them.

    Consider implementing patterns such as:

    • Sequential Agents (Assembly Line): Where one agent plans, another researches, and a third writes.
    • Agents as Tools: A main agent that can call other sub-agents for specific tasks.
    • Worker Agents: An orchestrator that distributes tasks to a team of agents.

How to Read Execution Logs

The best debugging tool is the execution history itself.

  • Green vs. Red Nodes: A green node executed successfully. A red node is where the error occurred.
  • The Inspection Panel: Click on any node after an execution and select “Inspect outputs.” You will see the exact outputs it produced. This allows you to trace the data flow step-by-step and see where it was corrupted or changed unexpectedly.

Would you like me to help you draft a Multi-Agent workflow for a specific task you have in mind?