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

Pin a Haystack Version for an Index

Run an index on a specific haystack-ai version or with extra packages by adding a dependencies block to the index YAML.

About This Task​

By default, an index runs on the Haystack version that Haystack Platform provides. To use a specific haystack-ai version or extra packages, add a top-level dependencies block to the index YAML. The index then processes your files in an isolated environment built from that block, so your pinned version doesn't depend on the version Haystack Platform uses. The block works the same way in index YAML you create or update through the API.

The dependencies block works like this:

  • Whole index runs in the pinned environment. This includes the DocumentWriter and every batch of files.
  • Validated up front. Haystack Platform checks the block when the index starts. If the block is invalid or empty, the indexing job fails immediately with an error message that describes the problem, before any file is processed.
  • Components must load on the platform. Haystack Platform still loads the index configuration with its own Haystack version to set up the document store. If a component exists only in a package or version you add in the dependencies block, the index can fail to start. Check the index logs for details.

If a batch fails in the pinned environment, the failure appears in the index logs as in any other index, and a missing document store index shows the same file status error. If tracing is on for the files, the trace of the failed batch is still saved so you can inspect it.

info

Pin the haystack-ai version with == so that re-indexing files later produces the same results.

Prerequisites​

The index must be disabled. For details, see Edit an Index.

Pin the Version​

  1. Log in to Haystack Enterprise Platform and open Indexes.

  2. Click the name of the index you want to update and switch to Build.

  3. In the index YAML, add a top-level dependencies block. Pin the haystack-ai version with == and list any extra packages:

    dependencies:
      - haystack-ai==2.18.0
      - <extra-package>

  4. Save the index.

  5. Enable the index. For details, see Enable an Index. When indexing starts, we validate the dependencies block.

  6. Open the Index Details page and check the logs. If the block is invalid or empty, the indexing job fails right away with an error message that describes the problem, before any file is processed. Fix the block and enable the index again. If the block is valid, indexing continues and processes your files.

On the Index Details page, check the processed files to confirm your files were indexed.

Remove the Pin​

To remove the pin, delete the dependencies block from a disabled index and enable it again. The index then runs on the version Haystack Platform provides.