Most problems come down to the agent not finding the command, the sign-in, the app's folder, or a token's level. Below are the messages your agent or the CLI shows, what each means and what you do. Start with ploa doctor: it checks Node, ploa, git, Xcode, CocoaPods, Java, the Android SDK, Flutter, disk space, the sign-in and whether the folder is linked.
The agent doesn't show Ploa
Restart the agent after ploa mcp install or a settings change. Most agents read MCP settings only when they start.
Check the file is where the agent looks:.mcp.json (Claude Code), .cursor/mcp.json, .vscode/mcp.json in the project's top folder, ~/.codex/config.toml for Codex. Open the agent in that folder. In Claude Code, approve the project's servers when asked.
Command not found: an agent opened from the Dock may not see your PATH. Run ploa mcp install again (it writes full paths), or use the full path from command -v npx.
Node too old: the server needs Node 24 or newer. node --version shows yours.
On Windows: 'ploa' not recognized, scripts disabled, or the agent not starting Ploa after an npm install: see Working from Windows.
Ploa's tools turned off: in Cursor's MCP settings or VS Code's tools list, turn ploa on.
Messages and what to do
Signing in
It says
What to do
This machine isn't signed in to Ploa. Ask the person to run ploa login in a terminal
Run ploa login on that computer (an agent can't sign itself in), or give the server a token as PLOA_TOKEN. In the terminal the same is not signed in: run ploa login.
this token is unknown or revoked
The token was revoked in Settings › Tokens, or by ploa logout. Run ploa login again, or make a new token. An agent on the web: connect it again.
the code expired before it was confirmed: run ploa login again
Run ploa login and confirm the code in the browser while it's shown.
This code is unknown, already used or expired (in the browser)
Run ploa login again and use the new code.
The wrong account or level
Run ploa whoami, or ask the agent to call ploa_access. A PLOA_TOKEN in the environment wins over ploa login: remove it if it's an old one.
can't reach https://ploa.dev, or didn't answer within … seconds
The computer can't reach Ploa: check the connection, a proxy or VPN, and that PLOA_SERVER isn't set to another address.
Which app
It says
What to do
This folder isn't linked to an app in Ploa: ploa_setup_guide says what's missing, and ploa_link links it
Ask the agent to run ploa_link. From a terminal, ploa init in the app's folder does the same.
the app has neither ios.bundleIdentifier nor android.package (or no applicationId or bundle ID, for an app that isn't Expo)
The app has no ID yet, so it can't be linked. Ask the agent to run ploa_setup_guide: it suggests IDs, and the agent sets the one you pick in the project.
several apple connections (…): choose one with --apple <name> (or google)
The workspace has more than one App Store or Google Play connection. Tell the agent which one, or run ploa init --apple <name>.
The agent works on the wrong app, or none
The server works on the app in the folder it starts in, from the nearest ploa.json. Start the agent in the app's folder, or add --dir /path/to/app to the server's arguments. One repository with several apps: each app's folder has its own ploa.json, and tools take the folder.
Say which app: pass app, its ID in Ploa (ploa_apps lists them)
On the web, with more than one app in the workspace: tell the agent which app, or ask it to list them.
A tool is refused
It says
What to do
this token can't ask for submit actions (or production actions)
The token's level is too low even to ask. Raise it in Settings › Tokens to Submit for review or Production; it keeps working with the new level. See the levels.
this token is limited to read (or draft, or submit)
The same: the action needs a higher level. Raise it in Settings › Tokens, or do it yourself on the dashboard.
an agent on the web asks a person for what needs this level, and doesn't do it itself
An agent on the web (Drafts, builds and requests) tried a store change it may only ask for, or one nobody asks for (uploading screenshots, a TestFlight group, sending the store page). Do it on the dashboard, or with the agent on your computer. If it's on Drafts and builds and should ask, change it to Drafts, builds and requests in Settings › Tokens.
an agent on the web does drafts and builds itself and asks a person for the rest
Settings › Tokens offers an agent on the web Read, Drafts or Drafts and requests, never Submit, Production or autonomous. For those, run the agent on your computer.
an agent on the web can't be autonomous
Run the agent on your computer if you want it autonomous.
an owner hasn't given you the "…" permission in this workspace
Your role doesn't include it, so neither do your agents. Ask an owner to turn it on for you on the Members page. The word in quotes is the permission: apps Apps and builds, store Store page, release App Review and production, reviews Reviews, keys Stores, keys and GitHub, sales Sales and revenue, agents Agents and tokens, billing Plan and billing, security Security, autonomous Autonomous agents.
only a signed-in person, or an agent its owner made autonomous, can do this
Do it yourself on the dashboard, or make the agent autonomous (Autonomous agents).
only a person can say App Privacy was entered in App Store Connect (or this was entered in Play Console)
Enter the answers in the console, then tick it in Ploa yourself. The agent tells you what to enter.
Data safety replaces what Play Console has, so a person sends it; the encryption declaration is the person's statement to Apple
Send it yourself from Ploa (Google Play setup › Data safety, or the Store details page), after checking the agent's answers.
Only a person can add the upload key for this agent
Add it in Ploa, in the app's Settings › Google Play › Add the key.
Not offered on the web (the tool isn't in the list)
Builds here, preflight, local files and simulator screenshots need the server on your computer.
the Free plan has room for 1 app: move to Pro for more (or a member count)
The plan's apps or members are full. Move to a bigger plan in Settings › Billing and usage, or remove an app you no longer need. See plans.
this workspace is suspended: its owners have an email from Ploa about it
The owners have the reason by email. Write to support if it's unclear.
link the app to its repository first
Ask the agent to run ploa_github_setup, then approve the link.
Not errors
It says
What it means
Waiting for a person's approval
Approve it on the dashboard or from the notification, and the agent follows with ploa_approval_status.
Kept in Ploa, not sent yet
Apple has the item with App Review. Ploa sends the change itself once Apple decides. Nothing to retry; ploa_held_changes lists what's kept.
Ploa was updated on this machine (… → …) after these tools started
Restart the agent, or reload its MCP servers, to use the new version.
A task in your approvals
A step only you can do in a store's console. Its steps and link are in the task, and the agent walks you through it.
Setting up the agent
It says
What to do
the file isn't plain JSON (comments?), so it was left alone
Name the agents with those words: ploa mcp install --agent claude,codex.
Node … is too old: ploa needs Node 24 or newer (install script)
Install Node 24 or newer from nodejs.org (or nvm, fnm, Homebrew), then run the script again.
… isn't on your PATH yet (install script)
Add the line it prints to ~/.zshrc or ~/.bashrc, then open a new terminal.
A build fails
Ask the agent: Why did the last release fail? It reads ploa_release_status and ploa_runs, step by step, fixes what's in the app's code, and runs ploa_setup_guide for what's outside it (an account, a capability at Apple, a store setting), which shows that step first, with its links.
Run ploa doctor on the computer: Xcode, Java, the Android SDK, disk space and the sign-in.
Run ploa preflight before building: it catches what the stores reject. A build from the terminal stops on what preflight finds (preflight found … problem(s)… fix them, or pass --force).
A build on GitHub missing google-services.json or .env: ploa files lists them and ploa files push sends them for your approval.
The web server (ploa.dev/mcp)
The approval page doesn't open: the agent opens it in your browser. Sign in to ploa.dev in that browser first, then try connecting again.
It worked, then stopped: the token may have been revoked in Settings › Tokens. Connect again.
A build tool asks for GitHub: on the web, builds run on GitHub. Ask the agent to run ploa_github_status.
It can't submit for App Review or release: an agent on the web asks only when you chose Drafts, builds and requests; then it asks and you approve. On Drafts and builds it can't even ask: change it in Settings › Tokens, or do it on the dashboard.
Still stuck?
Write to us on the support page with what you asked the agent, the tool's answer and the app. Never send a key or a password.
