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:

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

Error 403 Error when refreshing versions

This can happen for a number of reasons, but the root cause is Blender’s servers rejecting the HTTP requests to parse their version information. Largely, unless your IP is blacklisted, this is likely due to a firewall or proxy blocking the request. There are a few things you can try though:

• Disable any VPN you have active
• Disable any proxy you have active
• Check your firewall settings

If these do not work, you may need to wait for a while and try again, or try a different network such as a Phone hotspot.

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 Failed to attach Blender debugger

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

If you are already using PyCharm 2026.1 or newer and still receive this error, you may ignore it.

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 Blender console does not report an invalid or missing add-on root.

The extension repository name is managed internally and is no longer editable in Project Blender Manager. 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

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