> ## Documentation Index
> Fetch the complete documentation index at: https://cli-docs.relai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose common RELAI setup, simulation, evaluation, and optimization problems.

A low behavioral score, an evaluator error, and a broken runtime need three different responses.

## First: classify the outcome

<CardGroup cols={3}>
  <Card title="Low score">
    This is valid behavioral evidence. Read the evaluator feedback and first failing turn; do not repair or blindly rerun it.
  </Card>

  <Card title="Evaluator error">
    Report it separately. The agent’s behavior may still be usable evidence, but the missing score is not a zero.
  </Card>

  <Card title="Runtime failure">
    Fix Docker, dependencies, credentials, mounts, or provider setup before interpreting agent quality.
  </Card>
</CardGroup>

<Warning>
  **Do not blind-retry agentic workflows**

  Read the reported session and recovery command first. An unfinished write may need `--resume`; restarting can discard saved progress or repeat provider cost.
</Warning>

## Common first-run problems

<Accordion title="RELAI says a provider value is missing">
  Add the named variable to the ignored local `.relai/simulator.env` file, your shell, or a secure CI secret. Never paste its value into chat, commit it, or put it in a copied command.

  RELAI OAuth signs the CLI into RELAI; your agent’s provider key is a separate runtime value.
</Accordion>

<Accordion title="Docker, Compose, or uv is unavailable">
  Run the prerequisite audit, then start Docker and confirm its daemon is reachable before retrying the dependent workflow.

  <Tabs>
    <Tab title="Ask your coding agent">
      <Prompt description="Use RELAI to diagnose the missing host prerequisite. Check Docker without changing my project and explain the exact fix." actions={["copy"]}>
        Use RELAI to diagnose the missing host prerequisite. Check Docker without changing my project and explain the exact fix.
      </Prompt>
    </Tab>

    <Tab title="Run in terminal">
      ```sh theme={"system"}
      relai setup --check
      docker info
      ```
    </Tab>
  </Tabs>

  Host prerequisites cannot be repaired from inside an agent-test image.
</Accordion>

<Accordion title="My coding agent cannot find the RELAI skills">
  Install or refresh the matching local package, then activate it for the host: start a new Codex or Cursor session, run `/reload-plugins` in Claude Code, or use an interactive Copilot session.

  See [Coding-agent plugins](/plugins) for the exact command and host-specific step.
</Accordion>

<Accordion title="No agent tests exist after init">
  Initialization creates the simulator and EvalsWiki; it does not need to create an agent test. Inspect the curated risks, then target one.

  <Tabs>
    <Tab title="Ask your coding agent">
      <Prompt description="Use RELAI to show my EvalsWiki risks and propose one high-value agent test. Wait before creating it." actions={["copy"]}>
        Use RELAI to show my EvalsWiki risks and propose one high-value agent test. Wait before creating it.
      </Prompt>
    </Tab>

    <Tab title="Run in terminal">
      ```sh theme={"system"}
      relai wiki list risks
      relai test discover --risk <risk-id>
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="A workflow reports an unfinished session">
  Use the exact resume command printed by RELAI. Use `--restart` only when you deliberately want to discard the unfinished session and start over.

  Do not invent a resume command or reuse a stale interaction response.
</Accordion>

<Accordion title="The agent image is missing Python or a dependency">
  This is an image dependency problem, not an agent behavior score. Every RELAI agent image needs `python3` for the launcher, even when the project itself is TypeScript or Go.

  Repair the image or re-run initialization so the project-owned runtime setup includes the missing interpreter or package.
</Accordion>

<Accordion title="A macOS container sees an empty temporary mount">
  Some Docker/Colima configurations do not expose macOS system temporary paths inside Linux containers. Use a host-visible task-specific temporary directory under your user directory, then resume or restart the owning RELAI workflow as instructed.

  Keep this diagnosis separate from application imports: the same project can work correctly once the host mount is visible.
</Accordion>

<Accordion title="The command timed out">
  A timeout is not an agent score. Read stderr to learn whether progress was saved. Resume when RELAI provides a resume path; otherwise rerun only after checking the underlying cause and budget.
</Accordion>

## Results and artifact confusion

<Accordion title="Scores are not in EvalsWiki">
  This is expected. EvalsWiki stores durable requirements, risks, decisions, and open questions. Scores and conversations live in run artifacts under `.relai/.internal/runs/`.

  See [The learning loop](/learning-loop) for the complete artifact map.
</Accordion>

<Accordion title="The suite says “success,” but an evaluator score is low">
  Execution success means RELAI obtained and parsed a valid result. It does not mean the agent passed every evaluator. Read every score and its maximum.
</Accordion>

<Accordion title="I cannot check out the optimizer branch">
  The branch is usually already checked out in the optimizer worktree. Locate it and inspect that directory directly.

  <Tabs>
    <Tab title="Ask your coding agent">
      <Prompt description="Find the RELAI optimizer worktree and show me its branch and diff without changing either checkout." actions={["copy"]}>
        Find the RELAI optimizer worktree and show me its branch and diff without changing either checkout.
      </Prompt>
    </Tab>

    <Tab title="Run in terminal">
      ```sh theme={"system"}
      git worktree list
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Balanced mode did not report cost savings">
  Balanced mode changes the optimizer’s objective; it does not guarantee that comparable token or dollar telemetry will appear in the report. If the artifacts contain no numeric cost evidence, report **Cost change: not measured**.
</Accordion>

## Useful information when asking for help

* The RELAI version and exact public command used
* The terminal exit status and sanitized error category
* Whether the failure occurred before, during, or after agent execution
* The test ID, evaluator ID, and local artifact path
* Whether a resumable session or retry constraint was reported

<Warning>
  **Never include secrets**

  Do not share provider values, OAuth credentials, environment-file contents, or unrelated private project data in a support report.
</Warning>

<Card title="Return to a bounded first run" href="/quickstart">
  Once the prerequisite is fixed, resume the smallest selected workflow.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.