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

Troubleshoot Pipelines and Indexes

Diagnose and resolve common issues with pipelines and indexes.

Pipeline Issues​

When creating or updating a pipeline, you may see validation messages that appear in the Issues panel. These messages come in two categories:

  • Errors — block deployment. You must resolve all errors before you can deploy the pipeline.
  • Warnings — non-blocking hints about your configuration. Warnings do not prevent deployment; the pipeline deploys successfully even if warnings are present. Review them to make sure your configuration is intentional.

Here are common errors and how to resolve them.

Find and Fix Issues Faster

Builder has a global Issues panel at the bottom of the canvas, next to the Connections tab. It shows all validation and runtime issues in one place. Click Inspect next to any issue to jump directly to the affected component or connection.

Unconnected Model Provider​

Symptoms: The Issues panel in Pipeline Builder shows a model connection issue for an LLM or Agent component.

What happens: When a component such as LLM or Agent is configured to use a model provider that isn't connected to Haystack Enterprise Platform, an issue appears in the Issues panel. The issue shows the name of the affected model and provider.

Solution:

  1. Open your pipeline in Pipeline Builder.
  2. At the bottom of Builder, click Issues to open the Issues panel.
  3. Find the model connection issue and click Connect next to it.
  4. Enter your API key and any other required details for the provider.
  5. Click Connect to save the integration.

The issue disappears once the provider is connected. For general information on connecting model providers, see Connect to Model and Service Providers.

Missing Required Component Inputs Warning​

Symptoms: The Issues panel shows a warning that one or more components are missing required inputs.

What happens: When a component in your pipeline has required inputs that are not connected, the platform shows a warning in the Issues panel. Warnings are informational — they do not block deployment. You can deploy the pipeline and the warning remains visible until you address it.

Solution:

Review the warning and decide whether the missing input is needed for your use case:

  • If the input is required for your pipeline to work correctly, connect the missing input before deploying. Use the Inspect button next to the warning to help you.
  • If the input is optional for your scenario, you can deploy the pipeline as-is. The warning continues to appear in the Issues panel as a reminder.

Invalid Streaming Component Error​

If your pipeline contains components that don't support streaming, this error is shown:

Error message: "Invalid streaming component - This pipeline contains a component that does not support streaming. Remove or replace the incompatible component to enable streaming."

Solution: To resolve this error:

  1. Identify which components in your pipeline don't support streaming.
  2. Either remove the incompatible component or replace it with a streaming-compatible alternative.
  3. For more information about streaming and compatible components, see Enable Streaming.

Pipeline Builder Canvas Fails to Load​

Symptoms: Instead of the visual canvas, Pipeline Builder shows an error message with Retry and Switch to YAML buttons.

What happens: Pipeline Builder requires several resources to render the visual canvas correctly — including component definitions, input/output metadata, and visualization data for your pipeline. If any of these fail to load, Builder shows an error state rather than an empty or broken canvas. This prevents you from accidentally working with an incomplete graph.

What you can do:

  • Retry: Click Retry to reload the failed resources. Builder automatically retries a few times when a resource fails; the Retry button lets you trigger this manually after the automatic retries are exhausted.
  • Switch to YAML: Click Switch to YAML to open the YAML editor. The YAML editor does not depend on the visual canvas resources, so you can still view and edit your pipeline configuration while the issue resolves.
info

Your pipeline is not affected by this error. The YAML configuration — the source of truth for your pipeline — remains intact. Autosave and manual save are paused while the canvas is in this state to prevent incomplete data from being saved.

If the error persists:

  1. Refresh the page and reopen the pipeline.
  2. Check your network connection and verify there are no connectivity issues.
  3. If the problem continues, contact deepset support.

Pipeline Stuck in Deploying​

Symptoms: The pipeline status shows deploying for an extended period of time and does not change.

What happens: The platform automatically detects pipelines that have been deploying longer than expected and marks them as failed to deploy. This usually happens within a few minutes. Once the status changes to failed to deploy, you can redeploy the pipeline.

Solution:

  1. Wait a few minutes for the platform to detect the stuck deployment and update the status to failed to deploy.
  2. Once the status has changed, redeploy the pipeline. For details, see Deploy a Pipeline.
  3. If the pipeline fails to deploy again, check the pipeline YAML for configuration errors.

Pipeline Performance Issues​

Symptoms: Pipeline is slow or times out.

Possible causes and solutions:

  • Model latency: Try switching to a faster model or enable GPU acceleration. For details, see Enable GPU Acceleration for Pipelines.
  • Network bottlenecks: Check connectivity to external services and document stores.

Index Issues​

Index Status: Partially Indexed​

  • Symptoms: All of the files were processed, but at least one of the files failed to be indexed.
  • Possible causes and solutions:
    • Missing dependencies: Ensure all required components and integrations are properly configured. If you're unsure about whether a component is correctly configured, you can run it in isolation to see if it works. For details, see Run Components and Pipelines in Builder.
    • Invalid YAML configuration: Check your pipeline YAML for syntax errors.
    • Corrupted files: Check if you your files are OK. You can use the get indexed files by status endpoint to see the status of the files.
    • Retry indexing: Reindex the failed files:
      1. Go to Indexes and click the index that you're troubleshooting. This opens the Index Details page.
      2. Under Files, click More Actions next to a failed file and choose Retry Indexing.

Indexing Performance Issues​

Symptoms: Indexing is slow or search results are poor.

Possible causes and solutions:

  • Document preprocessing: Optimize document splitting and cleaning strategies.
  • Embedding model choice: Consider choosing different embedding models for your content.
  • Index settings: Adjust document store settings for better performance.

Debugging Tools​

For details on how to debug your pipelines, see Debugging Pipelines.