CLI Troubleshooting

Use symptoms → probable cause → fix. Defer to domain owners where appropriate.

Authentication / licensing

• Symptom: CLI prompts for login/token or reports entitlement failures.
• Cause: Missing/expired license or auth claim.
• Fix: See Technical/auth-licensing-sso/troubleshooting.md.

Analysis failures

• Symptom: analyze/tests exit 2 with parse errors or empty project warning.
• Cause: Invalid Ren’Py syntax, missing labels, or project path not detected.
• Fix: Confirm project root, run bpy doctor --project <path>, and review Technical/analysis/troubleshooting.md.

Telemetry / JSONL emissions

• Symptom: VS Code not receiving run notifications.
• Cause: BRANCHPY_EMIT_NOTIFY unset or extension capture disabled.
• Fix: Set BRANCHPY_EMIT_NOTIFY=1 (stdout) or BRANCHPY_EMIT_EVENTS=true (stderr). Ensure the extension setting branchpy.captureCli is enabled. See Technical/telemetry/troubleshooting.md and Technical/events/catalog.md.

PATH / Python environment

• Symptom: CLI not found, or Python import errors.
• Cause: BranchPy not on PATH, virtualenv inactive, missing dependencies.
• Fix: Activate env, reinstall package, or ensure bpy entry point resolves. Use bpy doctor --json to verify.

Permissions / filesystem

• Symptom: Cannot write reports or cache.
• Cause: Read-only project directory or cache directory.
• Fix: Grant write permissions to .branchpy/ and %LOCALAPPDATA%/BranchPy (or ~/.local/share/BranchPy). Override with BRANCHPY_CACHE_DIR if needed.

Config parsing

• Symptom: config commands fail with parsing errors (exit 3).
• Cause: Invalid TOML in .branchpy.toml or user config.
• Fix: Validate TOML, regenerate via bpy config init, or supply a clean file with --config. See Technical/cli/configuration.md.

SDK registry / matrix testing

• Symptom: Matrix runs fail with SDK not found.
• Cause: SDK registry missing entries or invalid paths.
• Fix: bpy renpy detect or bpy renpy add <name> <path> --validate; re-run bpy renpy list --validate.

Patches / history

• Symptom: undo/redo report no operations.
• Cause: Empty history stack or path mismatch.
• Fix: Run within the project root; check bpy history show --limit 10.