Troubleshooting

Runtime Logs

The plugin maintains a log file named blender_plugin.log in your project root. To ensure efficient disk usage, the plugin implements log rotation, keeping a history of recent logs while preventing the file from growing indefinitely. Check these logs if: - Blender fails to start or connection handshakes fail. - Reloading doesn’t seem to happen. - Symbolic links/junctions cannot be created.

Common Issues

• Windows Symlinks: On Windows, creating symbolic links may require Developer Mode enabled or Administrator privileges. If both fail, the plugin will attempt to create a Directory Junction as a fallback.

• macOS Compatibility: Prevented installation of Blender 5.0+ on Intel-based Macs. If your system is incompatible, a localized error message will be displayed during the download or setup process.

• Heartbeat Timeout: If the “Status” remains disconnected, check if a firewall is blocking the dynamic TCP port (defaulting to 5555).

• Metadata Cache: If the plugin fails to detect a newly installed (custom) Blender version, clearing the plugin’s internal cache may be necessary (stored in the IDE’s system directory).

• Bidirectional Heartbeat: The communication protocol uses a bidirectional heartbeat. Blender sends a “ready” signal upon startup. PyCharm uses retry logic (up to 5 attempts) to establish a stable TCP connection.

• Error Notifications: Critical communication errors are surfaced via IDE balloon notifications in addition to the blender_plugin.log.