zed-industries/zed · error · ValueError

ZedPierAgent requires EVAL_CLI_CONTAINER_PATH

Error message

ZedPierAgent requires EVAL_CLI_CONTAINER_PATH (the eval-cli binary on the mounted volume, e.g. /data/builds/<id>/eval-cli)

What it means

ZedPierAgent runs Zed's headless eval-cli binary inside a Pier container. The binary is not baked into the image; it lives on a runtime-mounted volume (for example /data/builds/<id>/eval-cli), so the agent looks up its container-side location through the EVAL_CLI_CONTAINER_PATH environment variable. When that variable is unset or empty, _container_binary_path raises this ValueError before any container work starts.

Solutions

Set EVAL_CLI_CONTAINER_PATH to the eval-cli binary path on the mounted volume, e.g. export EVAL_CLI_CONTAINER_PATH=/data/builds/<build-id>/eval-cli
Verify the binary exists at that path inside the container: ls -l /data/builds/<build-id>/eval-cli
Check the harness/job template actually passes the env var into the agent process (_get_env reads the agent env, not your shell)
Confirm you are going through the Pier runner that mounts the builds volume; running the agent on the host can never resolve the path

Example fix

# before
zed-eval launch --agent zed   # ValueError: ZedPierAgent requires EVAL_CLI_CONTAINER_PATH

# after
export EVAL_CLI_CONTAINER_PATH=/data/builds/4821/eval-cli
zed-eval launch --agent zed

Defensive patterns

Strategy: validation

Validate before calling

import os

binary_path = os.environ.get("EVAL_CLI_CONTAINER_PATH", "")
if not binary_path:
    raise SystemExit("EVAL_CLI_CONTAINER_PATH is not set; point it at the mounted eval-cli binary, e.g. /data/builds/<id>/eval-cli")
# only then construct/launch the agent

Try / catch

try:
    agent.run(...)
except ValueError as err:
    if "EVAL_CLI_CONTAINER_PATH" in str(err):
        raise SystemExit(f"missing env: {err}")
    raise

Prevention

Export EVAL_CLI_CONTAINER_PATH in the job template rather than ad hoc in shells
Add a startup assertion listing required env vars before launching any agent
Keep the build-id-specific volume path in one config variable so docs and env stay in sync

When it happens

Trigger: Constructing or running the 'zed' installed agent (install_spec()/run()) in a harness where EVAL_CLI_CONTAINER_PATH was never exported; typos in the variable name; running the agent outside the Pier job that mounts the /data/builds volume; a job template whose env block was dropped.

Common situations: Fresh CI/harness setup that forgot the env var; volume mount path changed after a deploy so documented paths no longer match; copy-pasting a launch command that references a different build id; sandbox or exec wrappers that filter environment variables.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of zed-industries/zed@f4178619ac (2026-08-20). Data as JSON: /api/errors/ae1e351637abf2fd. Report an issue: GitHub.

Appendix: source

Thrown at crates/eval_cli/zed_eval/pier_agent.py:76

    "OPENAI_BASE_URL",
    "OPENAI_API_BASE",
    "GEMINI_API_BASE",
)


class ZedPierAgent(BaseInstalledAgent):
    """Runs Zed's headless eval-cli binary under Pier."""

    SUPPORTS_ATIF: bool = False

    @staticmethod
    def name() -> str:
        return "zed"

    def _container_binary_path(self) -> str:
        path = self._get_env("EVAL_CLI_CONTAINER_PATH")
        if not path:
            raise ValueError(
                "ZedPierAgent requires EVAL_CLI_CONTAINER_PATH (the eval-cli binary "
                "on the mounted volume, e.g. /data/builds/<id>/eval-cli)"
            )
        return path

    def install_spec(self) -> AgentInstallSpec:
        # The binary lives on the runtime-mounted volume, which isn't available at
        # image-build time, so the real placement happens in run() via
        # exec_as_root. install_spec only needs a non-empty, no-egress step.
        return AgentInstallSpec(
            agent_name=self.name(),
            version=self._version,
            steps=[
                InstallStep(
                    user="root",
                    run="true  # eval-cli is copied from the volume at run time",
                )
            ],

View on GitHub (pinned to f4178619ac)