What causes "Invalid docstore strategy: {effective_strategy}" in run-llama/llama_index?

Use the enum constant instead of a string: from llama_index.core.ingestion.pipeline import DocstoreStrategy; IngestionPipeline(docstore_strategy=DocstoreStrategy.UPSERTS).

run-llama/llama_index · error · ValueError

Invalid docstore strategy: {effective_strategy}

Error message

Invalid docstore strategy: {effective_strategy}

What it means

Raised by IngestionPipeline's docstore-update step when the effective deduplication strategy is not one of the three DocstoreStrategy values (UPSERTS, DUPLICATES_ONLY, UPSERTS_AND_DELETE). The pipeline reads self.docstore_strategy (set at construction), so an arbitrary string or a mistyped value reaches this branch and is rejected before any docstore write.

Source

Thrown at llama-index-core/llama_index/core/ingestion/pipeline.py:536

    def _update_docstore(
        self,
        nodes: Sequence[BaseNode],
        effective_strategy: DocstoreStrategy,
        store_doc_text: bool = True,
    ) -> None:
        """Update the document store with the given nodes."""
        assert self.docstore is not None

        if effective_strategy in (
            DocstoreStrategy.UPSERTS,
            DocstoreStrategy.UPSERTS_AND_DELETE,
        ):
            self.docstore.set_document_hashes({n.id_: n.hash for n in nodes})
            self.docstore.add_documents(nodes, store_text=store_doc_text)
        elif effective_strategy == DocstoreStrategy.DUPLICATES_ONLY:
            self.docstore.add_documents(nodes, store_text=store_doc_text)
        else:
            raise ValueError(f"Invalid docstore strategy: {effective_strategy}")

    @dispatcher.span
    def run(
        self,
        show_progress: bool = False,
        documents: Optional[List[Document]] = None,
        nodes: Optional[Sequence[BaseNode]] = None,
        cache_collection: Optional[str] = None,
        in_place: bool = True,
        store_doc_text: bool = True,
        num_workers: Optional[int] = None,
        **kwargs: Any,
    ) -> Sequence[BaseNode]:
        """
        Run a series of transformations on a set of nodes.

        If a vector store is provided, nodes with embeddings will be added to the vector store.

View on GitHub (pinned to afd0fef371)

Solutions

Use the enum constant instead of a string: from llama_index.core.ingestion.pipeline import DocstoreStrategy; IngestionPipeline(docstore_strategy=DocstoreStrategy.UPSERTS).
If using strings, use exactly 'upserts', 'duplicates_only', or 'upserts_and_delete'.
Validate user-supplied strategy strings against DocstoreStrategy before constructing the pipeline.

Example fix

# before
pipeline = IngestionPipeline(docstore_strategy='upsert', ...)  # typo -> ValueError on run()

# after
from llama_index.core.ingestion.pipeline import DocstoreStrategy
pipeline = IngestionPipeline(docstore_strategy=DocstoreStrategy.UPSERTS, ...)

Defensive patterns

Strategy: validation

Validate before calling

from llama_index.core.ingestion.pipeline import DocstoreStrategy
DocstoreStrategy(pipeline.docstore_strategy)  # raises early with a clear message

Type guard

def is_valid_strategy(s) -> bool:
    try:
        DocstoreStrategy(s)
        return True
    except ValueError:
        return False

Try / catch

try:
    pipeline.run(documents=docs)
except ValueError as e:
    if 'Invalid docstore strategy' in str(e):
        pipeline.docstore_strategy = DocstoreStrategy.UPSERTS
        pipeline.run(documents=docs)
    else:
        raise

Prevention

Always pass DocstoreStrategy enum members, never strings
Validate config-sourced strategy strings with DocstoreStrategy(value) at startup
Remember valid values: upserts, duplicates_only, upserts_and_delete

When it happens

Trigger: Constructing IngestionPipeline(docstore_strategy='upsert') (wrong spelling; valid value is 'upserts'), 'duplicates-only', or any custom string not in the enum, then calling pipeline.run() with both docstore and vector_store set. The strategy flows through as a raw string and falls into the else branch.

Common situations: Typos in the docstore_strategy string (the enum values are 'upserts', 'duplicates_only', 'upserts_and_delete'); passing a strategy name from an old llama-index version or blog post; building the strategy from dynamic config/CLI input without validation.

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/814fc0e068befd25. Report an issue: GitHub.