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 lsto see the models you can use, andpw ai providers lsto 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 withpw authif 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 codeprompts you to pick from the allocations you may use; you can also run/allocationat 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. - Or switch to
automode with Shift+Tab, where a reviewer answers routine approvals for you. See Permissions. - 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.
A Turn Pauses with "Usage limit reached"
Symptom: The turn stops making progress and the transcript shows Usage limit reached, followed by Resuming at <time>.
Cause: The model's provider has a usage quota (such as a subscription's rolling window) that is used up until the time shown.
Solution: Nothing is lost: the turn, or the goal it belongs to, resumes by itself when the limit resets. Press Esc to stop waiting, or switch to a model from another provider with /model. Run /usage to see the provider's limits and reset times. 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
sessionRetentionDaysto a positive number, in which case thepw codedaemon 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
/settingsis enabled (thedisableSubagentssetting). - A session may spawn at most 200 subagents; once reached, the agent finishes work itself.
/clearresets 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
/mcpto see each server's status andpw code mcp listto see which config file is active. AnmcpServersmap 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
timeoutor theMCP_TIMEOUTenvironment 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.
pw code Refuses Its Configuration or State Directory
Symptom: pw code fails at startup with an error that a directory under ~/.config/pw or ~/.local/state/pw cannot be changed to mode -rwx------ (for example, keeps mode ... after a chmod to ...).
Cause: pw code keeps its settings, sessions, and daemon socket in directories only you can read. Some shared or network filesystems (such as GPFS and some CIFS or FUSE mounts) ignore the permission change, and pw code refuses to store your data where other users could read it.
Solution: Point XDG_CONFIG_HOME and XDG_STATE_HOME at directories you own on a local filesystem, and start pw code again. Keep them somewhere that persists, since your sessions are stored there.
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: runpw codeon the resource once to start the daemon.daemon_outdated: on the resource, runpw code daemon stop, thenpw codeto start the new daemon.- Otherwise, update
pwon 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.
Images Show as Placeholders Instead of Previews
Symptom: Images appear as text placeholders rather than inline pictures.
Cause: Inline previews need a terminal with image support, such as Kitty, Ghostty, WezTerm, or iTerm2, and are turned off inside tmux and Zellij.
Solution: The model still receives the full image, so nothing is lost. To see previews, run pw code directly in a supported terminal. See Interface & Shortcuts.
Getting Help
If the solutions above do not resolve your issue:
- Run
/statusin a session for a summary of the model, session, and configuration in effect. - Check the pw code overview for prerequisites and setup.
- Review AI Providers to verify your provider configuration.
Related Documentation
- pw code Overview: Feature overview and quick start
- Permissions: Permission modes and allow rules
- Models & Allocations: Model IDs and budget allocations
- Sessions & Resume: Session storage and retention
- Remote Control: The daemon, attach, and the web app
- Subagents: Delegation, the switcher, and limits
- MCP Servers: Server configuration and connection behavior
- Chat troubleshooting: Issues with the web chat interface