Skip to main content

Troubleshooting

Most LocalWP Devkit issues fall into four groups: the wrong folder is open, the project is not bound, Local has not exposed WP-CLI automation yet, or required runtime plugins are not installed in the Local site.

The Agent Is Editing the Wrong Folder​

Use the devkit root as the agent workspace:

oh-my-idetch-localwp-devkit/

Project source lives here:

projects/<slug>

The synced Local plugin copy is not source:

~/Local Sites/<site>/app/public/wp-content/plugins/oh-my-idetch

If changes were made directly in the synced plugin copy, move the intended source changes back into projects/<slug>, then run:

bun run project:check -- --project <slug>
bun run localwp:sync -- --project <slug>

Project Is Not Bound​

If localwp:sync, localwp:wp, or localwp:doctor says the project is unbound, bind it to a Local site:

bun run localwp:list
bun run localwp:bind -- --project <slug> --site "<Local site name>"

Use the exact Local site name shown by localwp:list or the Local app.

WP-CLI Is Unavailable​

localwp:wp depends on Local's generated Site Shell entry. If the command prints a fallback, open Local, select the site, choose Open Site Shell, then rerun the devkit command.

You can still continue with WordPress admin checks when WP-CLI is unavailable. Report the WP-CLI blocker clearly so the next session knows what happened.

Runtime Plugin Is Missing or Inactive​

If localwp:doctor warns that the plugin root is missing, sync first:

bun run project:check -- --project <slug>
bun run localwp:sync -- --project <slug>

Then activate the plugin:

bun run localwp:wp -- --project <slug> -- plugin activate oh-my-idetch

If WP-CLI is unavailable, activate oh-my-idetch in WordPress admin.

Premium Dependencies Are Missing​

The devkit does not bundle Etch, Etch Theme, OhMyEtch, AutomaticCSS, ACF Pro, WooCommerce, or other premium/user-owned plugins. Install and license those in the Local site.

Check the current runtime state:

bun run localwp:doctor -- --project <slug>
bun run localwp:capabilities -- --project <slug>

Missing optional plugins can be warnings when the project does not need them. They are blockers when the build depends on that runtime capability.

PHPStan Dependencies Are Missing​

If project:check reports a missing PHPStan binary, run the exact Composer command from the error. It will look like:

composer install --working-dir=projects/<slug>

Then rerun:

bun run project:check -- --project <slug>

Browser Verification Does Not Work​

Browser automation is optional. If it was not installed or failed to install, the project can still be created, checked, synced, and verified through LocalWP and WordPress admin.

Use the bound LocalWP domain from Local or project.json; do not assume a fixed localhost port.

The Local Site Shows Old Output​

Confirm that the source changed under projects/<slug>, not only in the synced plugin copy. Then run the required loop:

bun run project:check -- --project <slug>
bun run localwp:sync -- --project <slug>

If the page still shows old output, verify the oh-my-idetch plugin is active and the browser is loading the bound LocalWP domain.