Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Troubleshoot Agents

Fix common issues with Agents.


MCP Connection Error​

Pipeline Tool Shows Validation Warnings​

When you add a pipeline as a tool, deepset validates the pipeline before adding it. If the pipeline has non-fatal validation issues (warnings), the tool is still added to the Agent. The warnings are stored on the tool and are visible in the tool configuration.

Warnings do not prevent the tool from being used, but you should review them to make sure the pipeline behaves as expected. To inspect the warnings, open the tool configuration in the Agent's Tools panel.

If you see a hard validation error and the tool was not added, the pipeline has an issue that prevents it from being used as a tool. Open the pipeline in Builder, check the Issues panel for errors, and resolve them before trying to add the tool again. Click Inspect next to any error to jump to the affected component, or click Fix with AI to open the AI assistant, which reasons through the fix and can apply it for you.

Tool Description Is Not a Valid String​

Symptoms: Your pipeline returns an error that includes text like custom.description: Input should be a valid string when the Agent uses an Anthropic model.

What happens: Anthropic validates every tool definition sent with a request. If a tool in the Agent's tool list has a description field that isn't a valid string — for example, it's empty, set to None, or set to a non-string value — Anthropic rejects the request with an HTTP 400 error, and the pipeline run fails.

Solution:

  1. Open your pipeline in Pipeline Builder and find the Agent component.
  2. In the Agent's Tools panel, review each tool, including any pipelines added as tools.
  3. Make sure every tool has a non-empty string description.
  4. Save and redeploy the pipeline.

For more information on configuring tools, see Agent Tools and Configure an Agent.

Skills Environment Variable Not Set on a Nested Agent​

Symptoms: A pipeline that uses an Agent as a tool fails with an error like: None of the following authentication environment variables are set: ('DEEPSET_SKILLS_DIR_AGENT_...',).

What happens: Skills on an Agent used as a tool are supported, including Agents nested two levels deep. Each Agent with skills reads them from a folder that the platform prepares at deployment. Deployments from before October 30, 2026 prepared this folder only for the top-level Agent, so a nested Agent couldn't find its skills.

Solution:

  1. Redeploy the pipeline. The new deployment prepares skills for every Agent, nested ones included.
  2. When the deployment finishes, run the whole pipeline again to confirm the error is gone.

If redeploying fails because two Agents use the same skills variable with different sets of skills, give each Agent its own skills, or use the same set of skills in both.

Skills aren't available when you run a single component on its own. Run the whole pipeline to test an Agent that uses skills.