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``.