Skip to main content
Match the message you see to an entry below, run its diagnostic command, then apply its fix.
Symptom: entering /prflow: in Claude Code or $prflow: in Codex offers no PRFlow skills, or the client answers that the skill is unknown.List what the active client has loaded:
The plugin is prflow. The marketplace keeps the older name devflow-marketplace on purpose, so that name is not a sign of a stale install. If the plugin is absent, add the marketplace and install it:
Use only the two commands for your client. In Codex’s JSON output, the PRFlow entry must contain "installed": true and "enabled": true.Then start a new client session or chat. Claude Code can also run /reload-plugins. If the plugin is present but out of date, refresh its marketplace with the command for your client:
Codex CLI can also enter /plugins, open PRFlow and press Space to enable it. Enter /skills to confirm prflow:implement is available before retrying the request.
Symptom: on macOS the preflight prints a line of this form, even though you believe you installed a newer Python.macOS ships an older Python as python3 at /usr/bin/python3. On current releases that interpreter is Python 3.9. PRFlow needs Python 3.11 or newer. When a newer Python is installed but the system one comes first on PATH, PRFlow still resolves the old one.Check which interpreter PRFlow will find, and every python3 on your PATH:
If the first line reports 3.11 or newer, the gap is elsewhere. If it reports 3.9, install a newer Python and put it ahead of /usr/bin on your PATH. Homebrew installs it as:
Open a new shell, run python3 -VV again and confirm the version changed. Then run /prflow:init to repeat the check.
Do not delete or replace /usr/bin/python3. macOS uses it, and removing it can break other software on the machine. Change the order of PATH instead.
Symptom: the preflight prints one or more devflow preflight: lines and exits non-zero.PRFlow requires working git, gh, jq and Python 3.11 or newer reachable as python3. Run the check the supported way:
Initialization scaffolds the repository files and then runs the bundled preflight for you, reporting each gap with its remedy. The scaffold it already wrote stays in place even when the preflight reports a gap.On a GitHub Actions runner, or in a repository that commits the vendored plugin tree, the same check is available directly:
Install every dependency the check reports. A missing PyYAML is advisory on a local run: the preflight prints devflow preflight: required dependencies present; PyYAML advisory (see above). and still exits 0, but one severity helper is degraded until you install it:
Name the package. Do not install from a requirements file, because that path resolves against your own working directory and installs your project’s dependencies instead.
Symptom: the preflight prints devflow preflight: no working 'python3' on PATH, but a compatible Python (>=3.11) is available as ....Confirm which Python the shell can reach:
If either reports 3.11 or newer, install the supported python3 shim so PRFlow’s helpers resolve it:
Run the preflight again. The provisioner refuses to create a shim when no compatible interpreter exists, so a refusal means you still need a newer Python.
Symptom: the preflight reports no working gh or no working jq, and names a resolved path that does not execute. A non-executable shim shadowing the real tool causes this.Show every candidate the shell can see:
PRFlow probes gh and gh.exe, and likewise jq and jq.exe, and picks the first one that actually runs. Set an override when PATH still selects the wrong executable:
An override is used verbatim and is never probed, so point it at an executable you have confirmed. If the shell helpers are not running under a POSIX bash at all, install WSL bash, Git Bash or MSYS2 bash and set DEVFLOW_BASH where you invoke PRFlow.
Symptom: a PRFlow Python helper stops with a character-encoding error on a Windows host.PRFlow’s own Python helpers force their standard output and standard error to UTF-8 on their entry path, so non-ASCII output no longer raises an encoding error. If you see this, you are running an older version. Update the plugin:
On Linux and macOS the default codec is already UTF-8, so this never applies.
Symptom: installer output names a file as PRESERVED, and a new file appears beside it with a .prflow-new suffix.The installer could not prove the existing file was untouched since it wrote it, so it left your copy in place and wrote the new bytes to the sidecar.
1

Compare the two files

2

Merge the changes you want into your maintained file

Keep your local edits. Take the new behavior from the sidecar.
3

Delete the sidecar

Never commit a sidecar. A committed sidecar is dead weight and confuses the next update.
4

Re-run the installer in apply mode

Merging or adopting a sidecar changes the file’s bytes, so the digest the installer recorded for it is now stale. For a workflow the cloud implement gate depends on — .github/workflows/devflow-implement.yml, the setup-project-env action, or .prflow/lint-manifest.json — a stale .prflow/install-state.json marker makes the implement run refuse to start on every run until you re-apply. Re-running the installer in apply mode (--apply, or DEVFLOW_APPLY=1 for a curl | bash invocation) rebinds the marker to your merged bytes. The apply that preserved the file already warned you of this and named each affected sidecar.
If every file was preserved, Python probably could not run during the update, so the installer could not compare anything. Fix Python, then run the update again for a real comparison.