Skip to main content
Find your symptom below. Each entry says what you see, why it happens and how to fix it.
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

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.
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.
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.
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.
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.
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.
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.
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.

​
The SDK

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.
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.
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.
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:

​
Uploads and privacy

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.
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:
en_core_web_md and en_core_web_sm also work. For images and PDFs, install the anonymize-binary extra as well.
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.
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.
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

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.
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.
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.
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.
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

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.

​
Windows

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.
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.
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.
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

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.
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.
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. Then run the command it names to continue from where it stopped.
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 or post on Discord with the exact message, and attach the output of /plurai-diagnose.
Email support@plurai.ai or ask in the Plurai Discord. 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.