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

# Troubleshooting

> Symptoms and fixes for the problems you are most likely to hit when installing, connecting and running Plurai Simulation.

Find your symptom below. Each entry says what you see, why it happens and how to fix it.

> [!TIP]
>
> Signing in and installing the SDK happen inside the first command you run. If something about your login looks wrong, run `/harness-setup`: it tells you whether you're signed in and signs you in again.

## Install and connect

> [accordion] The browser sign-in didn't finish
>
> **Symptom:** a command stops with one line giving the reason, and `Run <command> again.`
>
> **Cause:** the sign-in in the browser was closed, timed out or not approved. The plugin never starts a second sign-in by itself, because each one opens a new page.
>
> **Fix:** run the same command again, or run `/harness-setup` to sign in on its own. If no browser opens, use the sign-in link the chat shows.

> [accordion] The command asks you to run /mcp reconnect all
>
> **Symptom:** after you sign in, the chat says *Run /mcp reconnect all to connect Plurai. I'll continue after that.*
>
> **Cause:** rare. The plugin normally picks up your login by itself, but here the session's connection to Plurai started without it.
>
> **Fix:** run `/mcp reconnect all`. The command carries on by itself. On Copilot CLI and Codex CLI, restart the coding agent if it asks you to, then run the command again.

> [accordion] You were signed in, and now a command asks you to sign in again
>
> **Symptom:** a command opens the browser sign-in although you signed in before.
>
> **Cause:** the saved key has expired or was revoked (for example by `plurai logout`). An expired key counts as no login.
>
> **Fix:** sign in again in the browser. Nothing else in your project changes.

> [accordion] A headless run says Plurai is not logged in
>
> **Symptom:** a `claude -p` or CI run stops with *Plurai is not logged in. Sign in once in an interactive session, then run this again.*
>
> **Cause:** a headless run can't open a browser to sign you in.
>
> **Fix:** sign in once in an interactive session on that machine, or for CI export `PLURAI_URL` and `PLURAI_TOKEN` with a key made in the Plurai dashboard. See [Environment variables](https://docs.plurai.ai/reference/environment-variables.md).

> [accordion] A command stops with flow-window: NOT READY
>
> **Symptom:** a command stops before doing anything, with a line like `flow-window: NOT READY (<check>): <what to fix>`.
>
> **Cause:** something the plugin can't fix inside the command, such as a hook that didn't run or, on Codex CLI, a shell with no network. On Codex CLI, choose **Trust all and continue** in the startup dialog. On Copilot CLI and Codex CLI, check that `python3` is on the `PATH` that launched the coding agent.
>
> **Fix:** apply what the line says, restart your coding agent, then run the command again.

> [accordion] /plugin marketplace add fails
>
> **Symptom:** adding the marketplace fails with a not-found error.
>
> **Fix:** check the name: `/plugin marketplace add plurai-ai/plurai-plugins`, then `/plugin install plurai-simulation@plurai-plugins`. The marketplace is public and needs no GitHub login.

> [accordion] A session starts with session\_pin could not write
>
> **Symptom:** a session starts with a notice that begins "session\_pin could not write", or a script says "the session pin cannot be used".
>
> **Cause:** the plugin keeps a small per-session file in `~/.plurai/pins` and couldn't write it. Usually your home folder isn't writable by your account (a Docker `--user` run, a Nix build, `sudo -E`), the disk is full, or the `pins` folder was created by another account.
>
> **Fix:** make your home folder writable by the account that runs the session, or delete `~/.plurai/pins` and start a new session. If you just updated the plugin, restart the session.

> [accordion] A Codex flow stops with plugin files changed
>
> **Symptom:** on Codex CLI, a flow refuses to start with "plugin files changed".
>
> **Cause:** newer Codex versions ask you to approve the plugin's hooks again after every plugin update.
>
> **Fix:** open `/hooks` in Codex and approve the plugin's hooks, then run the command again.

> [accordion] You don't get a report link at the end
>
> **Symptom:** the run finishes but no private link to the report is shared.
>
> **Cause:** Claude Code only publishes the report when you started it from your agent's folder or a folder above it. From anywhere else, the report stays on your machine.
>
> **Fix:** start `claude` from your agent's folder or a folder above it. The first time the report is published, Claude Code may ask once.

## The SDK

> [accordion] An upload command says the SDK is too old
>
> **Symptom:** an upload step stops with an upgrade hint, even though `plurai` is installed.
>
> **Cause:** every upload needs an SDK that sends data as raw parts (the `parts-only-upload` feature). The plugin checks `plurai capabilities` and refuses an older SDK, because an older one lists the same commands.
>
> **Fix:** say yes when the plugin offers to install the SDK. It installs the exact version it was tested with into your agent's environment. See [Install the SDK](https://docs.plurai.ai/sdk/install.md).

> [accordion] Flows are slow and use a lot of context, or say they could not check something
>
> **Symptom:** generation steps paste whole documents into the conversation, or job waits and backend checks say what they could not verify.
>
> **Cause:** no Python runner was found. The SDK is not installed in the project, or is too old. The flows still work, but they send documents inline (costing their full size in context on every call) and fall back to slower checks.
>
> **Fix:** install the SDK into your agent's virtual environment, or put the `plurai` command on your `PATH`.

> [accordion] The plugin will not use a plurai wrapper you wrote
>
> **Symptom:** a custom `plurai` script or wrapper in your project is not used, and the flow asks you to install the SDK.
>
> **Cause:** your token is in the runner's environment, so the plugin runs only a `plurai` that an installed SDK package lists. No variable or flag lifts this check.
>
> **Fix:** install the SDK into that environment.

> [accordion] The Run fails with No module named ... for your agent's own dependency
>
> **Symptom:** a scenario fails before the agent answers, naming a module your agent depends on, or `plurai` itself.
>
> **Cause:** the runner starts your agent with a Python interpreter that does not have your agent's dependencies.
>
> **Fix:** point the runner at your agent's environment. That environment needs your agent's dependencies and the `plurai` SDK:
>
> ```bash theme={null}
> export PLURAI_CHILD_PYTHON=/path/to/agent-venv/bin/python
> ```

## Uploads and privacy

> [accordion] An upload is refused for a mixed posture
>
> **Symptom:** an upload stops, saying the Environment already uploaded under the other anonymization posture.
>
> **Cause:** you changed `anonymize` in `plurai.config.yaml` after this Environment uploaded data. Mixing raw and anonymized data would break the links between records, so it is refused.
>
> **Fix:** set `anonymize` back to the posture the Environment used, or start a new Environment for the new posture. See [Data and privacy](https://docs.plurai.ai/security/data-and-privacy.md).

> [accordion] An anonymized upload refuses to run
>
> **Symptom:** with `anonymize: true`, an upload exits without sending anything.
>
> **Cause:** the local scrub is fail-closed. It needs the `plurai[anonymize]` extra and a spaCy English model.
>
> **Fix:** install the SDK with the `anonymize` extra, then a model:
>
> ```bash theme={null}
> python -m spacy download en_core_web_lg
> ```
>
> `en_core_web_md` and `en_core_web_sm` also work. For images and PDFs, install the `anonymize-binary` extra as well.

> [accordion] /trace-to-scenarios refuses under anonymization
>
> **Symptom:** `/trace-to-scenarios` stops when `anonymize: true`.
>
> **Cause:** turning conversations into resumed scenarios works only on raw data for now.
>
> **Fix:** use it in an Environment with the raw posture, or ground scenarios another way, such as `/analyze-traces`.

> [accordion] An upload is too large
>
> **Symptom:** an upload fails before sending, naming the largest files.
>
> **Cause:** the upload is over the backend's size limit. The SDK checks before it sends, so nothing left your machine.
>
> **Fix:** narrow the export. If your backend uses a different limit, set `PLURAI_INGEST_MAX_UNCOMPRESSED_BYTES` to it.

> [accordion] A script refuses to write output outside your project
>
> **Symptom:** a plugin script refuses an `--out` or `--out-dir` path.
>
> **Cause:** output must stay under the session's project directory, its `plurai_sim/` folder or the temp directory, and never in a place that runs code on its own, such as `.git`, `.claude` or `.vscode`.
>
> **Fix:** choose a path inside your project, or add `--allow-outside-workdir` to write elsewhere deliberately.

## Permissions and flow

> [accordion] Auto mode blocks a plugin script
>
> **Symptom:** under Claude Code's auto mode, the permission classifier denies a call to a plugin script.
>
> **Fix:** add an `autoMode.allow` entry to `~/.claude/settings.json`, keeping the `"$defaults"` entry, then restart Claude Code. See [Permissions](https://docs.plurai.ai/reference/permissions.md#if-the-classifier-blocks-a-plugin-script).

> [accordion] Auto mode prints a heartbeat notice
>
> **Symptom:** under auto mode, the flow prints a one-line notice that the heartbeat is not scheduled.
>
> **Cause:** auto mode denies creating scheduled jobs, so the plugin does not try. The flow still runs; it just cannot pick itself back up after a dropped turn.
>
> **Fix:** nothing is required. To restore the heartbeat, export `PLURAI_FLOW_HEARTBEAT=force` and add `CronCreate` to `permissions.allow`. See [Permissions](https://docs.plurai.ai/reference/permissions.md#the-dropped-turn-heartbeat).

> [accordion] A turn died on an API error
>
> **Symptom:** the flow stopped in the middle of a stage after an API error.
>
> **Fix:** run the same command again. It resumes where it stopped.

> [accordion] A run in CI stops on a question
>
> **Symptom:** a run with nobody at the terminal ends on a question.
>
> **Fix:** declare that nobody is there. Set `PLURAI_SIM_NONINTERACTIVE=1`, or `workspace.run_driver: headless` in `plurai.config.yaml`. Each question then takes its default, and anything only a person can supply stops with a clear finding. To approve fixes to the Harness in advance, also set `approve_harness_edits: true`. See [Configuration](https://docs.plurai.ai/reference/config.md#workspace).

> [accordion] A Run is recorded to LangSmith or Langfuse when you did not ask
>
> **Symptom:** a Run shows up in your observability platform.
>
> **Cause:** the SDK loads a `.env` file found above the current directory, and an `<PLATFORM>__ENABLED=true` in it stays in force.
>
> **Fix:** run with `--no-observability`, set `PLURAI_DISABLE_DOTENV=1`, or export `<PLATFORM>__ENABLED=false`. Choose **None** when `/simulation-run` asks about recording.

## Agents in other runtimes

> [accordion] The scan refuses your Node agent's runtime
>
> **Symptom:** the scan of a TypeScript or JavaScript agent stops and names what it refuses.
>
> **Cause:** the Node bridge supports Mastra, Vercel AI SDK, LangGraph.js, OpenAI Agents JS and custom loops on Node 22.15 or later. It refuses by name:
>
> * Bun and Deno,
> * a Windows host,
> * a Yarn Plug'n'Play install,
> * a `worker_threads` worker that a turn starts (refused when the Run starts it),
> * a raw SQL driver (`pg`, `mysql2` and similar) with no data-access module of the agent's own to mock.
>
> Any other language (Go, Java, Ruby and so on) is refused.
>
> **Fix:** run the agent on Node 22.15 or later with npm or a non-PnP install, and have Python with the SDK installed as well. A raw SQL driver can be mocked only when the agent reaches the database through a data-access module of its own. See [Node agents](https://docs.plurai.ai/integrations/node-agents.md).

## Windows

> [accordion] The readiness check could not run (exit 127)
>
> **Symptom:** `flow-window: the readiness check could not run (exit 127)`, or `plurai: no trusted python on this Windows host`.
>
> **Cause:** the plugin found no Python it trusts.
>
> **Fix:** install the Python launcher from python.org **for all users**, then restart the session.

> [accordion] Windows Subsystem for Linux has no installed distributions
>
> **Symptom:** a command fails with "Windows Subsystem for Linux has no installed distributions".
>
> **Cause:** a plain `bash` reached the WSL launcher instead of Git Bash.
>
> **Fix:** install Git for Windows, or set `CLAUDE_CODE_GIT_BASH_PATH` to your Git Bash, then restart the session.

> [accordion] python3 opens the Microsoft Store
>
> **Symptom:** typing `python3` opens the Microsoft Store.
>
> **Cause:** Windows' App execution aliases intercept the command.
>
> **Fix:** turn off the App execution aliases for Python in Windows settings.

> [accordion] A setting you just made is not seen
>
> **Symptom:** you set an environment variable, but the plugin doesn't see it.
>
> **Cause:** user environment variables reach new windows only.
>
> **Fix:** close the terminal, open a new one, and start your coding agent from it.

## Get help

> [accordion] Plurai is in high demand right now
>
> **Symptom:** a command stops with "Plurai is in high demand right now and we couldn't fit your run in."
>
> **Cause:** Plurai is at capacity for a short while. Nothing is wrong with your setup.
>
> **Fix:** wait about 20 minutes and run the same command again, or just send a message. It picks up where it stopped.

> [accordion] Plurai is unavailable right now
>
> **Symptom:** a command stops with "Plurai is unavailable right now."
>
> **Cause:** the Plurai service didn't answer, even after waiting and retrying.
>
> **Fix:** try again in a few minutes. The run picks up where it stopped.

> [accordion] A run stops for credit
>
> **Symptom:** a command stops with a sentence about your credit or plan, then tells you which command continues the run.
>
> **Cause:** your organization has used what its package includes, or reached its overage limit.
>
> **Fix:** an admin can upgrade the package or set an overage limit in [Usage & billing](https://docs.plurai.ai/using/web-app.md#track-usage). Then run the command it names to continue from where it stopped.

> [accordion] We hit an issue that needs a closer look from the Plurai team
>
> **Symptom:** a command stops with "We hit an issue that needs a closer look from the Plurai team", with a support email and Discord link.
>
> **Cause:** the failure can't be fixed from your machine, and a retry won't help.
>
> **Fix:** email [support@plurai.ai](mailto:support@plurai.ai) or post on [Discord](https://discord.gg/bg34gh76uJ) with the exact message, and attach the output of `/plurai-diagnose`.

> [accordion] Need help?
>
> Email [support@plurai.ai](mailto:support@plurai.ai) or ask in the
> [Plurai Discord](https://discord.gg/bg34gh76uJ). Include the command you ran, the message you saw, and the output of
> `/plurai-diagnose`, which never includes your token. Do not send your token.


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