Parallel Works
View as Markdown
Share:

Troubleshooting

Solutions to common issues when working with pw code. For problems with the web chat interface, see 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.

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.
  • 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 there is no picker: pass --allocation <name>.
  • If no allocations are listed, ask your organization admin for access. See Models & Allocations.

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.

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: read-only denies edits, and plan allows edits only to plan documents.

Solution: Check the mode in the status line and press Shift+Tab to cycle to accept-edits, or restart with --permission-mode accept-edits. Mode changes made with Shift+Tab 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.

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.

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

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 so they survive compaction, or raise the threshold with the compactAt setting. See Usage & 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.

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.

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.

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.

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.

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.

Images Will Not Paste

Symptom: Ctrl+V 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.

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 for prerequisites and setup.
  3. Review AI Providers to verify your provider configuration.

Related Documentation