Troubleshooting
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
| Symptom | What to do |
|---|---|
The opw or node command is not found | Restart 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 missing | Download the complete ZIP file again, extract it, and keep all files in the same directory |
| A conflict with files you modified is reported | The install script keeps your changes and reports the conflict instead of overwriting. Compare manually before deciding whether to overwrite |
| Dependency download fails | Check 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
| Symptom | What to do |
|---|---|
pilot-plugin-dev cannot be found | Confirm 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 fails | Ask the AI to read the full error, check the local build environment, and install missing components as prompted |
| A feature does not behave as expected | Provide 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 Issues. Include the following:
- The problem: the steps you took, the expected result, and the actual result.
- Your environment: the OPW version (run
opw --versionto 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.