Troubleshooting

2026-11-02Loading rating…

This page covers self-checks, repair, common installation and usage issues, and issue reporting.

Self-Check

Run the following in the project root:

opw doctor  # Check whether the project and AI capabilities are ready

Repair

After an OPW upgrade, if opw doctor reports that the project needs repair, run:

opw doctor --fix

After you confirm, the command creates a repair task and does not modify your plugin code directly. Then follow the prompts and let the AI complete the repair.

Installation Issues

SymptomWhat to do
The opw or node command is not foundRestart the terminal or AI tool, or load the activation file as described in Step 3 of the Quick Start. If you switch Node.js versions with a tool such as nvm, confirm the active version meets the requirement
Verification fails or files are missingDownload the complete ZIP file again, extract it, and keep all files in the same directory
A conflict with files you modified is reportedThe install script keeps your changes and reports the conflict instead of overwriting. Compare manually before deciding whether to overwrite
Dependency download failsCheck your network connection. To use a mirror, add --registry <npm registry URL> or --node-mirror <Node.js mirror URL> to the install command (-Registry and -NodeMirror on Windows)

Common Issues

SymptomWhat to do
pilot-plugin-dev cannot be foundConfirm opw doctor passes and restart the AI tool. In Claude Code, switch with /output-style pilot-plugin-dev; Codex has no pilot-plugin-dev, so invoke the opw Skill instead
Build failsAsk the AI to read the full error, check the local build environment, and install missing components as prompted
A feature does not behave as expectedProvide the operation, expected result, and actual result, and let the AI locate the cause before changing anything

Report an Issue

If none of the methods above solves the problem, report it in Mobile-SDK-Android-V5 GitHub Issuesopen in new window. Include the following:

  • The problem: the steps you took, the expected result, and the actual result.
  • Your environment: the OPW version (run opw --version to check), the operating system, and the AI tool you use.

Issues are publicly visible, so do not paste sensitive information such as your App Key.

Last Updated: