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 errors that prevent deployment. Here are common errors and how to resolve them.

Find and Fix Issues Faster

Use the global Issues panel in Builder. You can find it at the bottom of the canvas. Expand the panel to view all validation and runtime issues in one place. Click Inspect next to any issue to jump directly to the affected component or connection. Click Fix with AI to open the AI assistant, which reasons through the fix and can apply it for you.

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.

Components that use an embedded chat generator — such as LLMMetadataExtractor — are also checked for model connection status. If the configured provider is not connected, the Issues panel shows a warning for that component as well.

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.

Invalid Amazon Bedrock Model Identifier

Symptoms: Your pipeline returns an error similar to: "The provided model identifier is invalid."

What happens: Amazon Bedrock model IDs include a regional prefix (for example, us., eu., ap.) that must match the AWS region where your pipeline is deployed. If you configure a model ID with the wrong regional prefix — for example, using us.anthropic.claude-haiku-4-5-20251001-v1:0 in a deployment region that requires the eu. prefix — AWS returns a validation error (HTTP 400 ValidationException).

Solution:

1. Open your pipeline in Pipeline Builder and find the component that uses the Amazon Bedrock model.
2. Check the model ID configured in the component's settings.
3. Update the model ID to use the correct regional prefix for your deployment region. For example:
   • Use eu.anthropic.claude-... for deployments in European regions.
   • Use us.anthropic.claude-... for deployments in US regions.
   • Use ap.anthropic.claude-... for deployments in Asia Pacific regions.
4. For a full list of model IDs and supported regions, see Amazon Bedrock model IDs.
5. Redeploy your pipeline.

For more information on setting up Amazon Bedrock models, see Use Amazon Bedrock Models.

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.

OpenSearch Filter Missing Operator

Symptoms: Your pipeline returns an error like FilterError: 'operator' key missing when running a query with filters against an OpenSearch retriever.

What happens: OpenSearch retrievers such as OpenSearchBM25Retriever and OpenSearchHybridRetriever require filters to follow a structured format with three keys: field, operator, and value. Passing a flat dict — for example, {'year': 2024} — raises this error because the required operator key is missing.

Solution:

Update your filter to use the correct structured format:

{
  "field": "year",
  "operator": "==",
  "value": 2024
}

For combining multiple conditions, use a logical operator with a conditions list:

{
  "operator": "AND",
  "conditions": [
    {"field": "year", "operator": ">=", "value": 2020},
    {"field": "category", "operator": "==", "value": "news"}
  ]
}

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.

Your pipeline is safe

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 Files page.
    2. 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.