# Troubleshooting

> Source: https://parallelworks.com/docs/ai/code/troubleshooting

# Troubleshooting

Solutions to common issues when working with `pw code`. For problems with the web chat interface, see [Chat troubleshooting](/docs/ai/chat/troubleshooting).

## pw code Is Not Recognized or Lacks a Feature

**Symptom:** The `pw code` command is missing, or a feature described in these docs does not exist in your install.

**Cause:** The CLI is not installed or is outdated.

**Solution:** Check your version with `pw --version` (or `/version` inside a session) and update to the latest release. See the [CLI documentation](/docs/cli).

## No Models Available

**Symptom:** The model picker is empty, or `pw code` reports that no models are available.

**Cause:** No AI provider is configured for your account, or none is shared with you.

**Solution:**

- Run `pw ai models ls` to see the models you can use, and `pw ai providers ls` to see your providers.
- If both are empty, configure a provider or ask your administrator for access. See [AI Providers](/docs/ai/ai-providers).
- Verify you are authenticated: run `pw auth` and paste your credential when prompted.

## "An allocation is required for org provider models"

**Symptom:** Starting with an `org:` model fails with an allocation error, or a one-shot run exits immediately with this message.

**Cause:** Organization provider models draw from a budget allocation, and none is set.

**Solution:**

- In an interactive session, `pw code` prompts you to pick from the allocations you may use; you can also run `/allocation` at any time.
- In [non-interactive runs](/docs/ai/code/non-interactive) there is no picker: pass `--allocation <name>`.
- If no allocations are listed, ask your organization admin for access. See [Models & Allocations](/docs/ai/code/models).

## Invalid Model Format

**Symptom:** `pw code <model>` rejects the model ID.

**Cause:** Model IDs must have the form `owner:provider-name/model-name` and always contain a `/`.

**Solution:** Run `pw ai models ls` and copy the ID exactly, for example `Jake.Thayne:openai/gpt-5.2` or `org:openai/gpt-5.2`. See [Models & Allocations](/docs/ai/code/models).

## Authentication Expired Mid-Session

**Symptom:** Requests start failing with authentication errors partway through a session.

**Cause:** Your token or API key expired while the session was open.

**Solution:** Run `/auth` inside the session to re-authenticate without losing your conversation. Credentials are entered at a secure prompt. Never paste them into the chat itself.

## The Agent Will Not Edit Files

**Symptom:** Every edit is denied, or the agent only reads and plans.

**Cause:** The session is in a restrictive [permission mode](/docs/ai/code/permissions): `read-only` denies edits, and `plan` allows edits only to plan documents.

**Solution:** Check the mode in the status line and press <kbd>Shift</kbd>+<kbd>Tab</kbd> to cycle to `accept-edits`, or restart with `--permission-mode accept-edits`. Mode changes made with <kbd>Shift</kbd>+<kbd>Tab</kbd> persist as your default.

## Shell Commands Prompt Every Time

**Symptom:** The agent stops for approval on the same command over and over.

**Cause:** Approvals are per command; nothing is remembered unless you add an allow rule.

**Solution:**

- Add a rule from inside the session: `/permissions add Bash(git status:*)`. Rules added this way persist across sessions.
- Note that every part of a compound command must be covered by a rule, and commands containing `$(...)` or backticks are never auto-approved. See [Permissions](/docs/ai/code/permissions).

## Scripted Runs Fail on Approvals

**Symptom:** A `-p` run reports that commands were denied, or does less than expected.

**Cause:** One-shot runs cannot prompt, so any action that would need approval fails closed.

**Solution:** Pre-approve what the run needs with `--allowedTools` or `--add-dir`, or choose a mode that fits the job: `read-only` for analysis, `bypass-permissions` only in disposable environments. See [Non-Interactive Mode](/docs/ai/code/non-interactive).

## "Turn stopped: per-turn token budget reached"

**Symptom:** A turn ends with this message in the transcript.

**Cause:** The `maxTurnTokens` setting caps how many tokens a single turn may consume.

**Solution:** The session continues: send the next message to pick up where the turn stopped, or raise or unset `maxTurnTokens`. See [Usage & Costs](/docs/ai/code/usage-and-costs).

## The Agent Seems to Forget Earlier Context

**Symptom:** The agent stops referencing details from earlier in a long session.

**Cause:** When the live context reaches the compaction threshold, older messages are replaced with a summary.

**Solution:** This is expected in long sessions. Re-state the constraints that matter, keep them in [project instructions](/docs/ai/code/project-instructions) so they survive compaction, or raise the threshold with the `compactAt` setting. See [Usage & Costs](/docs/ai/code/usage-and-costs).

## A Session Is Missing from the Picker

**Symptom:** `pw code --resume` does not list a session you expect.

**Cause:** The picker defaults to sessions from the current directory; sessions in which you never sent a message are not saved; and sessions may have been swept if you enabled retention.

**Solution:**

- Switch **Scope** to **All** in the picker to see every saved session.
- Sessions are kept forever unless you set `sessionRetentionDays` to a positive number, in which case sessions untouched for that many days are deleted at startup. See [Sessions & Resume](/docs/ai/code/sessions).

## Sessions Do Not Appear in the Web Chat List

**Symptom:** Sessions from `pw code` are not visible in the Chat interface.

**Cause:** This is expected: `pw code` sessions are stored locally on your machine and are never uploaded to your account.

**Solution:** Resume local sessions with `pw code -r`. Chats saved to your account are separate; manage them with `pw ai chats`. See the [pw code overview](/docs/ai/code).

## The Agent Never Delegates to Subagents

**Symptom:** Asking the agent to parallelize or delegate does nothing, and the agent switcher never appears.

**Cause:** Subagents are disabled, or the session hit its per-session subagent budget.

**Solution:**

- Check that the **Subagents** row in `/settings` is enabled (the `disableSubagents` setting).
- A session may spawn at most 200 subagents; once reached, the agent finishes work itself. `/clear` resets the budget along with the conversation. See [Subagents](/docs/ai/code/subagents).

## A Subagent's Changes Are Not in My Files

**Symptom:** A subagent reports completed edits, but your working tree is unchanged.

**Cause:** Custom agents with worktree isolation run in a temporary git worktree, a separate checkout of the repository.

**Solution:** The subagent's report names the worktree path; fetch or merge its work from there. See [Worktree Isolation](/docs/ai/code/custom-agents#worktree-isolation).

## An MCP Server's Tools Are Missing

**Symptom:** A configured MCP server never connects, or its tools are not offered to the agent.

**Cause:** The server failed to start or connect, or its configuration is shadowed by a higher-precedence file.

**Solution:**

- Run `/mcp` to see each server's status and `pw code mcp list` to see which config file is active. An `mcpServers` map in a higher-precedence file replaces the whole map below it.
- Slow servers (for example, ones that download packages on first run) may need a longer timeout: set a per-server `timeout` or the `MCP_TIMEOUT` environment variable.
- A stdio server must keep stdout clean for the protocol and log to stderr only. See [MCP Servers](/docs/ai/code/mcp).

## Workspace Settings or Commands Are Not Applying

**Symptom:** A workspace's `.agents` settings, MCP servers, custom commands, or agent definitions have no effect.

**Cause:** Workspace configuration only applies after you approve it, and unapproved files are ignored. Non-interactive runs never prompt for approval.

**Solution:** Launch `pw code` interactively in that workspace and answer the approval prompt; the approval is remembered until the files change. See [Workspace Trust](/docs/ai/code/settings#workspace-trust).

## Images Will Not Paste

**Symptom:** <kbd>Ctrl</kbd>+<kbd>V</kbd> does not attach a clipboard image, especially over SSH.

**Cause:** Inside an SSH session your local clipboard is not reachable by the remote `pw code` process.

**Solution:** Copy the file to the remote machine (for example with `scp`) and attach it by path with `@~/screenshot.png` instead. See [Interface & Shortcuts](/docs/ai/code/interface).

## Getting Help

If the solutions above do not resolve your issue:

1. Run `/status` in a session for a summary of the model, session, and configuration in effect.
2. Check the [pw code overview](/docs/ai/code) for prerequisites and setup.
3. Review [AI Providers](/docs/ai/ai-providers) to verify your provider configuration.

## Related Documentation

- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [Models & Allocations](/docs/ai/code/models): Model IDs and budget allocations
- [Sessions & Resume](/docs/ai/code/sessions): Session storage and retention
- [Subagents](/docs/ai/code/subagents): Delegation, the switcher, and limits
- [MCP Servers](/docs/ai/code/mcp): Server configuration and connection behavior
- [Chat troubleshooting](/docs/ai/chat/troubleshooting): Issues with the web chat interface