fix: handle Skiko/Direct3D crash on Windows GPU configurations (#981)

backlog/tasks/task-203 - Document-Skiko-Direct3D-crash-fix-and-SOFTWARE-rendering-workaround-issue-981.md

@@ -0,0 +1,128 @@
+---
+id: TASK-203
+title: >-
+  Document Skiko/Direct3D crash fix and SOFTWARE rendering workaround (issue
+  #981)
+status: Done
+assignee: []
+created_date: '2026-03-09 11:34'
+updated_date: '2026-03-09 11:58'
+labels:
+  - documentation
+  - bug-fix
+  - windows
+dependencies: []
+references:
+  - 'https://github.com/devoxx/DevoxxGenieIDEAPlugin/issues/981'
+  - src/main/kotlin/com/devoxx/genie/ui/compose/SafeComposeContainer.kt
+  - >-
+    src/main/kotlin/com/devoxx/genie/ui/compose/ComposeConversationViewController.kt
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Document the fix for GitHub issue #981 where the plugin crashes with `UnsatisfiedLinkError` on certain Windows GPU/driver configurations when Skiko tries to initialize Direct3D rendering.
+
+**What was the problem:**
+- `ComposePanel.addNotify()` triggers Skiko's `Direct3DSwingRedrawer` which throws `UnsatisfiedLinkError`
+- Skiko's `RedrawerManager.findNextWorkingRenderApi()` only catches `RenderException`, not `Error`, so the error propagates and crashes the tool window
+
+**What was fixed (branch `fix/issue-981`):**
+- Added `SafeComposeContainer.kt` — a JPanel wrapper that catches `Throwable` during `addNotify()` and shows a fallback Swing panel with recovery instructions
+- Modified `ComposeConversationViewController.kt` to use SafeComposeContainer instead of creating ComposePanel directly
+- Tracks `composeInitFailed` flag to skip theme/appearance updates when in fallback mode
+
+**User workaround:**
+Add `-Dskiko.renderApi=SOFTWARE` to IDE VM options (Help > Edit Custom VM Options) to force software rendering.
+
+**Documentation needed:**
+- Add a troubleshooting entry to the Docusaurus docs covering this error and the workaround
+- Consider adding a FAQ entry about GPU driver compatibility
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Troubleshooting entry added to Docusaurus docs covering `UnsatisfiedLinkError` and the `-Dskiko.renderApi=SOFTWARE` workaround
+- [x] #2 FAQ entry added about Windows GPU driver/rendering compatibility
+- [x] #3 User can force software rendering before Compose initialization via Settings > Appearance checkbox and restart
+- [x] #4 Fallback error/help panel explains recovery steps, including the startup VM option and settings-based workaround, when Compose initialization fails
+- [x] #5 Task notes document that plugin-local runtime retry is not a robust fix and that startup/early-init renderer selection is the supported workaround
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+## Corrected completed plan
+
+1. Add and expose a persistent software-rendering preference.
+2. Apply `skiko.renderApi=SOFTWARE` before any Compose UI is initialized when that preference is enabled.
+3. Document the Windows rendering failure, the startup VM option workaround, and the settings-based workaround.
+4. Ensure the fallback/help panel provides recovery guidance instead of allowing the tool window to fail without instructions.
+5. Record the investigation outcome that plugin-local runtime retry is not the supported recovery path and that upstream/library-level fixes remain the stronger long-term option.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+## Corrected implementation record
+
+### Final understanding
+This task started with a runtime SOFTWARE-retry narrative, but follow-up source inspection showed that the important supported workaround is **pre-start renderer selection**, not plugin-local retry after initialization has already started.
+
+### What remains valid
+1. **User-facing workaround remains valid**
+   - `-Dskiko.renderApi=SOFTWARE` as a JVM startup option can bypass the Direct3D path on affected Windows systems.
+
+2. **Persistent plugin setting remains valid**
+   - The plugin exposes a "Force software rendering" setting that applies the renderer choice before Compose UI creation on next startup.
+
+3. **Fallback/help UI remains useful**
+   - If Compose initialization fails, the plugin can still catch the failure at the container boundary and show recovery instructions instead of hard-crashing the tool window.
+
+### What was corrected
+1. **Runtime retry is not a robust fix in this plugin**
+   - `ComposePanel` performs real Compose/Skiko initialization in `addNotify()`, not at simple construction time.
+   - A retry wrapped around panel creation is therefore not aligned with the actual failure boundary.
+
+2. **True native library load failures are one-shot**
+   - In Skiko `0.8.18`, `Library.load()` marks the library as loaded before `findAndLoad()` completes.
+   - If the native library load itself fails, later attempts are skipped.
+   - Changing `skiko.renderApi` afterward cannot recover that class of failure.
+
+3. **Runtime retry should not be treated as the supported recovery path**
+   - It is still theoretically possible for a fresh instance to observe a new renderer value in some post-load failure scenarios.
+   - But for this plugin, the current retry design should be considered unreliable and superseded by startup/early-init renderer selection.
+
+### Recommended supported behavior
+- Prefer early-start renderer selection via settings or JVM option.
+- Show a fallback/help panel with recovery instructions if Compose initialization still fails.
+- Treat upstream/local Skiko fixes or architectural renderer-path control as the stronger long-term direction.
+
+### Files relevant to the supported solution
+- `src/main/java/com/devoxx/genie/ui/settings/DevoxxGenieStateService.java`
+- `src/main/java/com/devoxx/genie/service/PostStartupActivity.java`
+- `src/main/java/com/devoxx/genie/ui/settings/appearance/AppearanceSettingsComponent.java`
+- `src/main/kotlin/com/devoxx/genie/ui/compose/SafeComposeContainer.kt`
+- `docusaurus/docs/getting-started/troubleshooting.md`
+- `docusaurus/docs/getting-started/faq.md`
+
+### Superseded notes
+Any earlier notes in this task that describe plugin-local automatic SOFTWARE retry as the definitive working fix should be treated as superseded by this corrected record.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+## Corrected summary
+
+Issue #981 is a Windows-specific Compose/Skiko initialization failure involving the Direct3D path. The durable, supported workaround is to select SOFTWARE rendering **before** Compose initialization, either through `-Dskiko.renderApi=SOFTWARE` at JVM startup or through the plugin's persisted "Force software rendering" setting applied on startup.
+
+The task now reflects that plugin-local runtime retry should not be treated as the robust fix. The reliable user-facing outcome is:
+- documented troubleshooting guidance
+- a settings-based startup workaround
+- a fallback/help panel with recovery steps when initialization fails
+
+Longer term, stronger fixes remain an upstream/local Skiko patch or a renderer-path architecture change in newer Compose/Skiko.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-203.1 - Design-and-implement-a-robust-non-retry-fix-path-for-Skiko-Windows-initialization-failures-issue-981.md

@@ -0,0 +1,46 @@
+---
+id: TASK-203.1
+title: >-
+  Design and implement a robust non-retry fix path for Skiko Windows
+  initialization failures (issue #981)
+status: To Do
+assignee: []
+created_date: '2026-03-09 11:59'
+labels:
+  - bug-fix
+  - windows
+  - compose
+  - skiko
+dependencies:
+  - TASK-203
+references:
+  - 'https://github.com/devoxx/DevoxxGenieIDEAPlugin/issues/981'
+  - src/main/kotlin/com/devoxx/genie/ui/compose/SafeComposeContainer.kt
+  - >-
+    src/main/kotlin/com/devoxx/genie/ui/compose/ComposeConversationViewController.kt
+  - src/main/java/com/devoxx/genie/service/PostStartupActivity.java
+  - >-
+    src/main/java/com/devoxx/genie/ui/settings/appearance/AppearanceSettingsComponent.java
+documentation:
+  - 'backlog://workflow/task-execution'
+  - >-
+    backlog/tasks/task-203 -
+    Document-Skiko-Direct3D-crash-fix-and-SOFTWARE-rendering-workaround-issue-981.md
+parent_task_id: TASK-203
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Follow up on issue #981 with an engineering fix that does not rely on plugin-local runtime retry after Compose initialization has already started. Task context: the corrected investigation on TASK-203 shows that the supported workaround is startup/early-init renderer selection (`-Dskiko.renderApi=SOFTWARE` or the persisted setting), while the current runtime retry narrative is not robust for this plugin. This follow-up should determine and implement the strongest viable long-term fix path, such as a local/upstream Skiko patch, a safer initialization boundary for recovery, or an explicit renderer-path architecture change in newer Compose/Skiko.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 A concrete long-term fix path for issue #981 is selected and documented, with rationale based on the corrected TASK-203 investigation
+- [ ] #2 The implemented solution no longer treats plugin-local runtime retry as the supported recovery mechanism for Windows Direct3D initialization failures
+- [ ] #3 Windows rendering failure handling remains user-recoverable through startup/early-init software rendering selection and fallback/help guidance if initialization still fails
+- [ ] #4 Relevant tests, diagnostics, or validation steps are added or documented so the chosen fix path can be verified without relying on the old retry narrative
+- [ ] #5 User-facing and task-facing documentation are consistent with the chosen fix path and do not describe plugin-local runtime retry as the definitive solution
+<!-- AC:END -->

docusaurus/docs/getting-started/faq.md

@@ -93,6 +93,14 @@ import Head from '@docusaurus/Head';
             "@type": "Answer",
             "text": "DevoxxGenie requires IntelliJ IDEA 2023.3.4 or later. It works with IntelliJ IDEA Community and Ultimate editions, as well as other JetBrains IDEs built on the IntelliJ platform (like PyCharm, GoLand, WebStorm)."
           }
+        },
+        {
+          "@type": "Question",
+          "name": "The chat UI doesn't load on Windows - how do I fix it?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "On some Windows GPU/driver configurations, the chat UI may fail to load with a Direct3D/Skiko error. DevoxxGenie v0.8.0+ automatically handles this by retrying with software rendering. To permanently fix it, go to Settings > DevoxxGenie > Appearance and enable 'Force software rendering (fixes GPU issues on Windows)', then restart IntelliJ IDEA. Alternatively, add -Dskiko.renderApi=SOFTWARE to your IDE VM options (Help > Edit Custom VM Options)."
+          }
         }
       ]
     }
@@ -191,6 +199,22 @@ Click **Refresh Models** in DevoxxGenie settings after pulling a new model. Make
 
 Switch to a smaller quantized model. For chat, try `llama3.2:3b` or `llama4:scout`. For inline completion, try `qwen2.5-coder:0.5b`. See the [Ollama performance tips](use-ollama-in-intellij.md#performance-tips).
 
+### The chat UI doesn't load on Windows — how do I fix it?
+
+On some Windows systems with certain GPU/driver configurations, the DevoxxGenie chat UI may fail to initialize with an error about Skiko/Direct3D.
+
+**Good news**: DevoxxGenie v0.8.0+ **automatically handles this** — if hardware rendering fails, it retries with software rendering and the UI should work normally.
+
+To permanently fix this issue:
+
+1. Go to **Settings** > **DevoxxGenie** > **Appearance**
+2. Enable **"Force software rendering (fixes GPU issues on Windows)"**
+3. **Restart IntelliJ IDEA**
+
+Or add `-Dskiko.renderApi=SOFTWARE` to your IDE VM options (**Help** > **Edit Custom VM Options**).
+
+See the [Troubleshooting guide](troubleshooting.md#chat-ui-not-loading--gpu-rendering-error) for more details.
+
 ### Where do I report bugs or request features?
 
 Open an issue on [GitHub](https://github.com/devoxx/DevoxxGenieIDEAPlugin/issues) or start a discussion in [GitHub Discussions](https://github.com/devoxx/DevoxxGenieIDEAPlugin/discussions).

docusaurus/docs/getting-started/troubleshooting.md

@@ -0,0 +1,180 @@
+---
+sidebar_position: 8
+title: Troubleshooting - DevoxxGenie
+description: Solutions to common issues when using DevoxxGenie, including GPU rendering problems, connection issues, and LLM configuration errors.
+keywords: [devoxxgenie troubleshooting, gpu rendering error, skiko error, unsatisfiedlinkerror, chat ui not loading, windows gpu fix]
+image: /img/devoxxgenie-social-card.jpg
+---
+
+# Troubleshooting
+
+This guide helps you resolve common issues when using DevoxxGenie.
+
+## Chat UI Not Loading / GPU Rendering Error
+
+### Problem
+On certain Windows systems with specific GPU driver configurations, the DevoxxGenie chat UI may fail to load with an error related to Skiko/Direct3D:
+
+```
+UnsatisfiedLinkError: Failed to load Direct3D native library
+```
+
+This occurs because the graphics rendering engine (Skiko) cannot initialize hardware-accelerated rendering on some GPU/driver combinations.
+
+### Automatic Fix (v0.8.0+)
+
+Starting with version 0.8.0, DevoxxGenie **automatically handles this issue**:
+
+1. First, it attempts hardware rendering (Direct3D/OpenGL)
+2. If that fails, it automatically retries with software rendering
+3. The chat UI should load normally without any action required
+
+You'll see a log message indicating the fallback was used:
+```
+Successfully initialized Compose with software rendering fallback
+```
+
+### Manual Workarounds
+
+If you still experience issues, or want to avoid the automatic retry delay, use one of these methods:
+
+#### Option 1: Force Software Rendering in Settings (Recommended)
+
+1. Open **Settings** (or **Preferences** on macOS)
+2. Navigate to **Tools** > **DevoxxGenie** > **Appearance**
+3. Scroll to **Rendering Settings**
+4. Check **"Force software rendering (fixes GPU issues on Windows)"**
+5. Click **Apply** and **OK**
+6. **Restart IntelliJ IDEA**
+
+This permanently enables software rendering and prevents the error from occurring.
+
+#### Option 2: VM Options (Alternative)
+
+Add the following system property to your IDE's VM options:
+
+1. Go to **Help** > **Edit Custom VM Options...**
+2. Add this line:
+   ```
+   -Dskiko.renderApi=SOFTWARE
+   ```
+3. Save the file
+4. **Restart IntelliJ IDEA**
+
+#### Option 3: Update GPU Drivers
+
+In some cases, updating your GPU drivers resolves the compatibility issue:
+
+- **NVIDIA**: [Download from nvidia.com](https://www.nvidia.com/drivers)
+- **AMD**: [Download from amd.com](https://www.amd.com/support)
+- **Intel**: [Download from intel.com](https://www.intel.com/content/www/us/en/support/detect.html)
+
+After updating drivers, restart IntelliJ IDEA and try DevoxxGenie again.
+
+### Still Not Working?
+
+If none of the above solutions work:
+
+1. Check the **IntelliJ IDEA log files** for detailed error messages:
+   - **Help** > **Show Log in Explorer/Finder**
+   - Look for errors related to `Skiko`, `Direct3D`, or `UnsatisfiedLinkError`
+
+2. Report the issue on [GitHub Issues](https://github.com/devoxx/DevoxxGenieIDEAPlugin/issues) with:
+   - Your operating system and version
+   - GPU model and driver version
+   - IntelliJ IDEA version
+   - The relevant error log excerpt
+
+## Ollama Connection Issues
+
+### Problem
+DevoxxGenie cannot connect to Ollama or models don't appear in the dropdown.
+
+### Solutions
+
+1. **Verify Ollama is running**:
+   ```bash
+   curl http://localhost:11434/api/tags
+   ```
+   If this fails, start Ollama: `ollama serve`
+
+2. **Check the base URL in settings**:
+   - Default should be: `http://localhost:11434`
+   - If using Docker or remote Ollama, adjust accordingly
+
+3. **Firewall/Antivirus**: Ensure port 11434 is not blocked
+
+4. **Model not showing**: Click **Refresh Models** in the provider dropdown
+
+See the full [Ollama setup guide](use-ollama-in-intellij.md) for more details.
+
+## API Key Errors
+
+### Problem
+Getting "Invalid API key" or "Authentication failed" errors with cloud providers.
+
+### Solutions
+
+1. **Verify the API key is correct**:
+   - Open DevoxxGenie settings
+   - Navigate to **LLM Providers**
+   - Select the provider and check the API key field
+   - Re-enter the key if unsure
+
+2. **Check key permissions**: Some providers require specific permissions or the key may be expired
+
+3. **Verify provider status**: Check if the LLM service is experiencing outages
+
+## Slow Responses with Local Models
+
+### Problem
+Local LLM responses are very slow or timeout.
+
+### Solutions
+
+1. **Use a smaller model**: Try `llama3.2:3b` or `qwen2.5-coder:1.5b` instead of larger models
+
+2. **Check system resources**:
+   - Monitor CPU/GPU usage during generation
+   - Ensure sufficient RAM is available
+   - Close unnecessary applications
+
+3. **Enable GPU acceleration for Ollama**:
+   ```bash
+   ollama run llama3.2 --gpu
+   ```
+
+See [Ollama performance tips](use-ollama-in-intellij.md#performance-tips) for more optimization suggestions.
+
+## Plugin Not Visible After Installation
+
+### Problem
+The DevoxxGenie icon doesn't appear in the IDE after installation.
+
+### Solutions
+
+1. **Restart IntelliJ IDEA** — required after plugin installation
+
+2. **Check if the plugin is enabled**:
+   - **Settings** > **Plugins** > **Installed**
+   - Look for DevoxxGenie and ensure it's checked
+
+3. **Invalidate caches**:
+   - **File** > **Invalidate Caches / Restart...**
+   - Select **Invalidate and Restart**
+
+4. **Verify IDE version**: DevoxxGenie requires IntelliJ IDEA 2023.3.4 or later
+
+## Getting Help
+
+If your issue isn't covered here:
+
+1. Check the [FAQ](faq.md) for common questions
+2. Search [GitHub Issues](https://github.com/devoxx/DevoxxGenieIDEAPlugin/issues) for similar problems
+3. Join [GitHub Discussions](https://github.com/devoxx/DevoxxGenieIDEAPlugin/discussions) for community support
+4. Create a new issue with:
+   - Clear description of the problem
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Environment details (OS, IDE version, plugin version)
+   - Relevant log excerpts