Troubleshooting

Start with the symptom below, then review the plugin log when the suggested fix does not resolve it.

Blender is not discovered

The scanner checks common installation locations on Windows, macOS, and Linux. If a scan finds nothing:

Confirm Blender is installed and can be launched directly.
Set a custom installation root in Settings > Tools > Blender Development.
Run the scan again and review warnings in the plugin log.
You can always select the executable or macOS application bundle directly in Project Blender Manager.

Launch says the Blender path is empty

Select Blender in Project Blender Manager, save the project configuration, and retry the Blender run configuration.

Debugging reports `Debugpy not supported`

Upgrade to PyCharm 2026.1 or newer. The plugin’s debugger uses Python DAP with debugpy, which is not supported by its older IDE baseline.

Runtime changes do not appear

Restart the sandbox IDE or relaunch Blender so the plugin can compare and re-extract its bundled runtime. Contributors testing locally may need to rebuild the plugin resources first.

An extension is not loaded

Confirm that:

blender_manifest.toml contains the expected extension ID.
Project Blender Manager points to the correct source folder.
The configured extension repository name matches the intended Blender repository.
The Blender console does not report an invalid or missing add-on root.

The plugin enables extensions by their authoritative bl_ext.<repository>.<id> module name. Traditional add-ons continue to use the configured add-on or directory name.

Runtime commands stop responding

Restart the Debug session. Unreachable sessions are removed from the active cache after bounded request timeouts.

Diagnostic checklist

Confirm the Blender path and source folder in Project Blender Manager.
Retry with no additional Blender arguments.
Check the configured plugin log location.
Re-run installation discovery and inspect its warnings.
Restart PyCharm to clean stale generated bootstrap scripts.