Troubleshooting

ppd's messages say what failed and what to do next. This page collects them by command, with the fix. A message that starts with refused: is a safety guard (exit code 3): see the safety model.

Install and dev loop

client-rejected

my-plugin: client-rejected (installed)
client: the app would not evaluate this plugin's client, so none of its UI appears:
  Unknown Lucide icon: HandWaving

The daemon installed the plugin and its server runs, but the app would refuse the client bundle, so no panel, screen or Command Center item shows up anywhere, and Paseo itself says nothing. ppd install exits 1; ppd dev prints the same lines and keeps watching. Each line under client: is a registration rule the app enforces, for example:

  • Unknown Lucide icon: X: the app's Lucide build has no icon named X.
  • Command Center item X has no icon, Workspace panel X has invalid context, Screen X is not a component.
  • client.X is not part of the app's plugin client context (calling it throws).
  • Plugin contribution must return a cleanup function.

Fix the line, save, and ppd dev re-checks on reload. ppd check reports the same rules as client-eval.

Where the logs are

  • Plugin output (console.log in server code, load and stop lines): npx ppd paseo -- plugin logs <plugin id>. ppd install prints the plugin log; ppd dev prints the new lines after each reload.
  • The daemon's own output: daemon.out in the dev home that ppd daemon status prints.
  • The browser console: ppd web prints console errors after every run.

ppd check

APPROXIMATION

SKIP  paseo-compile    APPROXIMATION: no Paseo app or PASEO_SOURCE found: install Paseo, or set PASEO_APP to Paseo.app or PASEO_SOURCE to a getpaseo/paseo checkout with node_modules. Compile, evaluation and icon checks below use an esbuild replica and rules vendored from Paseo, not the host itself

ppd found neither the Paseo desktop app nor a Paseo checkout, so it compiled with an esbuild replica of Paseo's build options. That is expected on Linux CI. On a Mac, install Paseo or point PASEO_APP (or --paseo-app) at it. --approx forces the replica on purpose. See Host-contract checks.

could not load Paseo's plugin compiler

FAIL  paseo-compile    could not load Paseo's plugin compiler from the Paseo 0.12.0 app (/Applications/Paseo.app): expected ... ppd was verified on Paseo 0.11.4 and found 0.12.0, so this release may lay things out differently. Run `ppd check --approx` for the esbuild replica, or set PASEO_SOURCE to a getpaseo/paseo checkout. Please report it at ...

ppd reads the compiler, the evaluator and the Lucide list from inside the installed app, which is not a public API. A Paseo release that moves them breaks this, not your plugin. Use ppd check --approx or PASEO_SOURCE, and report it with the message. The same pattern covers the icon list (lucide-icons warns and falls back), agentTimeline and web UI labels. What ppd relies on is listed on Compatibility.

Hermes checks skipped

SKIP  hermes-parse     hermesc not found (install react-native as a devDependency, or set HERMESC)
SKIP  hermes-vm        Hermes VM not found (react-native ships it for macOS; or set HERMES)

Add react-native as a devDependency (the templates do), or set HERMESC and HERMES to the binaries. Without them, only hermes-class (no class syntax) guards the phone.

The evaluation did not finish

... did not finish within 30 s (an infinite loop or a blocking call at load or in contribute?)
... did not finish within 120 s (an infinite loop or a blocking call at load or in contribute?)

Plugin code runs in a child process with a time limit: 30 s for the client, and for the server on the approximation; with the app or a checkout the server is evaluated inside the compile step, which has 120 s. A blocking loop at module load or in contribute ends here. plugin code called process.exit(N) means what it says: the host would lose the whole plugin process. A timer or server left running after the cleanup is a warning, not a failure.

Dev daemon

no running dev daemon

no running dev daemon "default": run `ppd daemon up` first

install, dev, paseo, web and android (without --port) need a daemon. With --name N on daemon up, pass the same --name N to the others. A record whose process is gone is cleaned up by the next ppd daemon up.

Ports

port 7810 is already in use: pick another --port or omit it
no free port in 7800-7899; pass --port
dev daemon "default" is already running on port 7800: run `ppd daemon down` first, or pass --name for a second daemon

Without --port, ppd takes the first free port from 7800 to 7899. ppd daemon status --all lists ppd's dev daemons, and ppd doctor shows the running ones.

Paseo CLI not found

Paseo CLI not found: install Paseo, put `paseo` on PATH, or pass --paseo / PASEO_BIN

ppd looks at --paseo or PASEO_BIN, then paseo on PATH, ~/.local/bin/paseo and /Applications/Paseo.app/Contents/Resources/bin/paseo. An explicit path that does not exist is an error, never a fallback to another Paseo.

dev daemon exited early

The message ends with the daemon's last output and how ppd started it: paseo daemon run --home <home> with PASEO_HOME and PASEO_LISTEN set and a config.json in the home. When the Paseo version differs from the verified one, the message says so: a new release may have changed the flags.

ppd web

No web UI

this dev daemon has no web UI: restart it with `ppd daemon up --web-dist <dir>`

The web UI comes from the desktop app (Paseo.app/Contents/Resources/app-dist) or PASEO_WEB_UI_DIST_DIR. ppd daemon up prints (no web UI build found: pass --web-dist) next to the URL when it found none.

No browser

no browser for Playwright: install Google Chrome, run `npx playwright-core install chromium`, or set PPD_BROWSER

No workspace opened

2 workspaces on the dev daemon, none opened: pass --workspace <id, name or dir> (ids: wks_..., wks_...)
no workspace on the dev daemon, showing the start page: `ppd daemon up --workspace <dir>` creates one

With one workspace, ppd web opens it. paseo run --cwd DIR creates a workspace per new directory, so fake agent runs in several directories leave several.

The web UI did not show ...

the Paseo web UI did not show the workspace (a "Workspace actions" button) within 30 s. ppd finds it by the labels of the Paseo 0.11.4 web UI; a different version may have renamed it ...

ppd web finds the app shell, workspaces and the Command Center by their accessible names. On a Paseo other than 0.11.4 a renamed label ends here; please report it. On 0.11.4, retry with --headed to watch what the page does.

Fake agent

fake-agent: invalid script: ...
fake-agent refused to run this command: bash steps with run: true work only in a dev daemon started by `ppd daemon up`, and this daemon's home was not created by ppd

A prompt that starts with a brace or a bracket must be a valid script. Shell steps with run: true only run in ppd's own daemons. See Fake agent.

npx ppd runs something else

Outside a project that has paseo-plugin-devkit installed, npx ppd resolves to an unrelated npm package named ppd. Use npx --package paseo-plugin-devkit ppd <command>, or install the devkit as a devDependency first.