SC26AI agents lab + dinner on the river · Nov 17
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 whoami, and sign in again with pw auth if needed. See Authentication.

"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 sign in again without losing your conversation. It opens browser sign-in and shows the sign-in link and code in a panel, so it also works over SSH. Where browser sign-in is unavailable, it asks for an API key or token at a hidden prompt instead. Never paste a key or token into the chat itself. /auth works only in the terminal running pw code; from another client, run pw auth on that machine.

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:

  • Choose Yes, and don't ask again for in the prompt to save the suggested rule for this repository.
  • Or add a rule from inside the session: /permissions add Bash(git status:*) saves it for this repository, and /permissions add user Bash(git status:*) for every workspace.
  • Every part of a compound command must be covered by a rule, and commands containing $(...) or backticks are never auto-approved.
  • Some prompts cannot be lifted by a rule: destructive commands, commands that write outside the workspace or set environment variables, and changes to pw code's own configuration. See Permissions.

"Command blocked"

Symptom: A shell command fails with Error: command blocked and names the current permission mode.

Cause: The command matched a shell command check. sudo, system commands, and commands that install packages or change containers, clusters, or infrastructure are blocked in every mode except bypass-permissions. In read-only and plan, anything that writes is blocked too.

Solution: Allow rules do not lift these blocks. Run the command yourself in shell mode with the ! prefix, switch modes with Shift+Tab, or use bypass-permissions in a disposable environment.

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 the pw code daemon deletes sessions untouched for that many days when it starts and every 6 hours after. 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.

The Daemon Will Not Start

Symptom: pw code fails with socket path ... exceeds the unix socket path limit.

Cause: The pw code daemon listens on a socket in your state directory, and socket paths have a short length limit. A deeply nested XDG_STATE_HOME exceeds it.

Solution: Set XDG_STATE_HOME to a shorter path, such as ~/.local/state.

For other daemon problems, check its log at ~/.local/state/pw/code-daemon-<host>.log, and run pw code daemon status to see whether it is running. See Remote Control.

Attaching to Another Machine Fails

Symptom: pw code attach reports cannot reach the pw code daemon, or mentions no_daemon or daemon_outdated.

Cause: No daemon is running on the resource, the resource's pw is too old to have one, or its daemon is from an older release than its pw.

Solution:

  • no_daemon: run pw code on the resource once to start the daemon.
  • daemon_outdated: on the resource, run pw code daemon stop, then pw code to start the new daemon.
  • Otherwise, update pw on the resource. See Remote Control.

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