Skip to content
Floogos

AI Agents — Common problems and solutions

Troubleshooting guide. Each case describes the symptom, the cause and how to configure it to fix it.

”The agent has no brain connected”

Section titled “”The agent has no brain connected””

Symptom: the agent fails right away with that message and doesn’t answer.

Cause: there’s no Brain (LLM) connected to the brain port, or the sub-node ended up without attach_to/role.

Solution:

  • Verify you dragged the brain’s output to the brain port (the purple one, below the agent), not to another port.
  • If you configured it by hand, confirm the brain has role = brain and attach_to = the exact agent alias (e.g. aiAgent_1).
  • Remember: one brain only. If you connected two, the last one replaces the previous.

The tool never runs

Section titled “The tool never runs”

Symptom: the agent answers, but ignores the tool even though the request warrants it.

Causes and solutions:

  1. Poor description. The LLM decides to use a tool by reading its tool_description. If it’s vague, it won’t use it. → Write an explicit description: what it does and when to use it.

  2. The tool is gated by a skill. If the tool_name is in some skill’s enables_tools, it only appears when that skill activates. → Either activate the skill (with its keywords), or remove the tool from enables_tools.

  3. max_iterations too low. If the task chains several tools, the loop may cut off early. → Raise max_iterations on the agent.

  4. Missing tool_schema. Without a schema, the LLM doesn’t know which arguments to pass and may avoid the tool. → Define the JSON schema of the parameters.

The tool runs but errors out

Section titled “The tool runs but errors out”

Symptom: in the trace you see Node 'X' not found or an error from the executed node.

Causes and solutions:

  • node_type misspelled. It must be the node’s real type (e.g. the CSV node is csvparce, not csvRead). → Check the exact name in the palette or in the module list.
  • Missing base node data. Some nodes need fixed config (credentials, endpoint…). → Load it in node_config (JSON). It’s merged with the arguments the LLM decides.
  • Tool-node credential. If the executed node needs a credential (e.g. an ERP), pass its id in node_config.

RAG returns empty or irrelevant results

Section titled “RAG returns empty or irrelevant results”

Symptom: the agent can’t find the context, answers generically or “I don’t have that information”.

Cause #1 — different namespace. You indexed into one namespace and retrieve from another. → Use exactly the same namespace in RAG (ingest) and RAG (retrieve).

Cause #2 — different embeddings model. The indexing and query embeddings must come from the same model; otherwise the vectors aren’t comparable. → Match provider + model in both nodes (e.g. openai / text-embedding-3-small in both).

Cause #3 — never indexed. The ingestion workflow didn’t run, or ran without data. → Run the ingestion first and confirm there was indexed > 0 in its output.

Cause #4 — top_k too low or chunks too large. → Raise top_k, or lower chunk_size in the ingestion for more specific chunks.

The skill doesn’t activate (or activates always)

Section titled “The skill doesn’t activate (or activates always)”

Symptom: the skill doesn’t apply when it should, or the other way around.

Cause: activation depends on the user request matching the keywords or words in the description.

Solution:

  • If it does not activate: add more representative keywords (CSV) from the user’s real vocabulary.
  • If it activates too much: narrow the keywords and make the description more specific.
  • Remember that tools in enables_tools stay hidden until the skill activates — if a tool must always be available, don’t put it in a skill.

Credential error / 401 / model not found

Section titled “Credential error / 401 / model not found”

Symptom: the brain fails when calling the LLM.

Solutions:

  • Confirm the brain’s credentials_id matches the chosen provider (an OpenAI key doesn’t work for Anthropic).
  • Verify the model exists for that provider (e.g. gpt-4o, claude-sonnet-5, mistral-large-latest).
  • For local LLM: the local credential must have the correct base URL and the server (Ollama/vLLM) must be up with the model loaded.

Sub-nodes “run on their own” or appear in the flow

Section titled “Sub-nodes “run on their own” or appear in the flow”

Symptom: it looks like the brain/tool/skill runs by itself.

Cause: they were connected as data flow (arrow to the left/right ports) instead of to the role port (bottom edge).

Solution: delete that connection and drag the sub-node’s output to the corresponding role port of the agent. Role sub-nodes must not have flow arrows towards the agent; the orchestrator consumes them, it doesn’t run them in the sequence.

The agent “falls short” on complex tasks

Section titled “The agent “falls short” on complex tasks”

Symptom: it leaves tasks half done when they require several steps with tools.

Solution:

  • Raise max_iterations (each round = one round of tool calls).
  • Split large capabilities into smaller, well-described tools.
  • Consider a workflow-kind tool that wraps a multi-step process into a single call.

Back to the start

Section titled “Back to the start”