chroma-core/chroma · error · ValueError

The {self.api_key_env_var} environment variable is not set.

Error message

The {self.api_key_env_var} environment variable is not set.

What it means

PerplexityEmbeddingFunction.__init__ resolves its API key as api_key or os.getenv(api_key_env_var) and raises this ValueError when the result is empty. The env var name defaults to PERPLEXITY_API_KEY, and the constructor hard-preferences PERPLEXITY_API_KEY when it is set (otherwise it uses the api_key_env_var parameter). Passing api_key directly works but now triggers a DeprecationWarning because raw keys are not persisted in collection config.

Source

Thrown at chromadb/utils/embedding_functions/perplexity_embedding_function.py:59

            raise ValueError(
                "The perplexityai python package is not installed. Please install it with `pip install perplexityai`"
            )

        if api_key is not None:
            warnings.warn(
                "Direct api_key configuration will not be persisted. "
                "Please use environment variables via api_key_env_var for persistent storage.",
                DeprecationWarning,
            )

        if os.getenv("PERPLEXITY_API_KEY") is not None:
            self.api_key_env_var = "PERPLEXITY_API_KEY"
        else:
            self.api_key_env_var = api_key_env_var

        self.api_key = api_key or os.getenv(self.api_key_env_var)
        if not self.api_key:
            raise ValueError(
                f"The {self.api_key_env_var} environment variable is not set."
            )

        self.model_name = model_name
        self.dimensions = dimensions
        self._client = perplexity.Perplexity(api_key=self.api_key)

    def __call__(self, input: Documents) -> Embeddings:
        """
        Generate embeddings for the given documents.

        Args:
            input: Documents to generate embeddings for.

        Returns:
            Embeddings for the documents.
        """
        response = self._client.embeddings.create(

View on GitHub (pinned to aecdd12c8a)

Solutions

1. export PERPLEXITY_API_KEY=pplx-... in the environment that runs the process (docker-compose environment:, Kubernetes Secret -> env, CI secret variable), then restart.
2. Or point at a differently-named existing variable: PerplexityEmbeddingFunction(api_key_env_var="MY_PPLX_KEY").
3. Or pass the key directly for quick tests: PerplexityEmbeddingFunction(api_key="pplx-...") — expect a DeprecationWarning and avoid committing it.
4. If using .env, call load_dotenv() before creating the embedding function and confirm with a quick assert os.getenv("PERPLEXITY_API_KEY").

Example fix

// before
ef = PerplexityEmbeddingFunction()  # ValueError: The PERPLEXITY_API_KEY environment variable is not set.

# after
import os
from dotenv import load_dotenv
load_dotenv()
ef = PerplexityEmbeddingFunction(
    api_key_env_var="PERPLEXITY_API_KEY"  # resolves from env
) if os.getenv("PERPLEXITY_API_KEY") else PerplexityEmbeddingFunction(api_key=os.environ["PPLX_TOKEN"])

import os

PPLX_VAR = "PERPLEXITY_API_KEY" if os.getenv("PERPLEXITY_API_KEY") else "MY_PPLX_KEY"
if not os.getenv(PPLX_VAR):
    raise RuntimeError(f"{PPLX_VAR} is not set — export it before constructing PerplexityEmbeddingFunction")

def has_perplexity_key() -> bool:
    return bool(os.getenv("PERPLEXITY_API_KEY") or os.getenv("PPLX_API_KEY"))

try:
    ef = PerplexityEmbeddingFunction()
except ValueError as e:
    if "environment variable is not set" in str(e):
        raise RuntimeError("Missing Perplexity credentials — set PERPLEXITY_API_KEY") from e
    raise

When it happens

Trigger: Constructing PerplexityEmbeddingFunction() with no api_key argument in a shell/container where PERPLEXITY_API_KEY is not exported; or passing api_key_env_var="MY_PPLX_KEY" when that custom variable is unset. Because __init__ also builds perplexity.Perplexity(api_key=...) right after, failure is immediate.

Common situations: Key stored in .env but load_dotenv() called after construction; key present in the IDE terminal but not in the Docker/Kubernetes/CI environment; variable name typo (PERPLEXITY_KEY, PPLX_API_KEY) not matching the default; free-tier users who never created an API key in the Perplexity console.

Related errors

• The {self.api_key_env_var} environment variable is not set.
• The {self.api_key_env_var} environment variable is not set.
• The {self.api_key_env_var} environment variable is not set.
• The {self.api_key_env_var} environment variable is not set.
• The {self.api_key_env_var} environment variable must be set

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/772e16dcbd50852b. Report an issue: GitHub.