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 launches 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. Select the executable or macOS application bundle directly in Project Blender Manager if necessary.

Refreshing versions returns HTTP 403

Blender’s server rejected the version-discovery request. A VPN, proxy, firewall, or temporary server restriction may be the cause. Disable an active VPN or proxy, check firewall rules, and retry later or from a different trusted network.

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

Confirm you are using PyCharm 2026.1 or newer. Then:

1. Open Settings > Python > Debugger.
2. Scroll to Debugger mode.
3. Select debugpy and apply the setting.
4. Stop the existing Blender run and start a new Debug session.

Do not ignore the attach error solely because add-on reload or other runtime commands still work. Runtime commands use a separate communication channel and can remain available without an attached Python debugger.

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 not editable in Project Blender Manager. The plugin enables extensions by their authoritative bl_ext.<repository>.<id> module name. Traditional add-ons use their 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 without 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.

When reporting a problem, include the plugin, PyCharm, Blender, operating-system, and Python versions; the smallest reproduction; and the full first error with credentials and personal paths removed.