Troubleshooting & Common Issues
Relevant source files
The following files were used as context for generating this wiki page:
The Kaleidux system is a high-performance wallpaper daemon that integrates several complex subsystems, including WGPU for hardware-accelerated rendering, GStreamer for video decoding, and Unix IPC for control. Troubleshooting typically involves diagnosing issues within the rendering pipeline, resource management, or configuration validation.
This guide provides a technical overview of common failure points and the diagnostic tools available within the codebase to resolve them. It covers system metrics, common error states, and IPC communication failures.
System Monitoring and Metrics
Kaleidux includes a robust performance monitoring system that tracks frame times, resource utilization, and potential memory leaks. This system is the primary tool for diagnosing "stuttering" or high resource usage.
Performance Metrics Tracking
The PerformanceMetrics struct tracks several key indicators to help identify bottlenecks in the rendering or decoding pipelines.
| Metric | Purpose | Threshold/Note |
|---|---|---|
frame_times | Tracks latency of the last 100 frames. | Targets ~16.6ms for 60 FPS. |
memory_samples | Records memory usage in MB over time. | Used to detect growth rates. |
error_count | Total number of internal errors recorded. | Increments on decode or render fails. |
texture_pool | Tracks hits/misses in the WGPU texture cache. | High miss rate indicates resource thrashing. |
Sources: kaleidux-daemon/src/metrics.rs:7-60
Resource Leak Detection
The daemon monitors resource counts to detect leaks in the WGPU pipeline or IPC channels. It specifically watches for growth in textures and pipelines that are not being cleaned up by the cleanup_texture_pool task.
The monitor checks if the texture count has grown by more than 50 over a 60-second window or if the frame channel exceeds 20 queued frames, which indicates the renderer cannot keep up with the decoder.
Sources: kaleidux-daemon/src/metrics.rs:431-480, kaleidux-daemon/src/main.rs:945-950
Common Rendering and Hardware Issues
WGPU and Driver Initialization
A known issue involves WGPU waiting for driver initialization on Wayland, which can take approximately 15 seconds. If the daemon appears hung on startup, it is often waiting for the WgpuContext::with_surface call to return.
Sources: README.md:104, kaleidux-daemon/src/main.rs:414-420
GPU and Shader Support
Kaleidux requires Vulkan or GLSL 450 support. Shader compilation errors often occur if the GPU drivers are outdated or if the environment lacks the necessary Vulkan headers.
Sources: README.md:106, kaleidux-daemon/errors.txt:3
Frame Throttling and Stalling
To prevent memory ballooning, Kaleidux implements throttling logic. If Wayland frame callbacks are stuck for more than 1000ms, the daemon stops uploading new video frames to prevent staging buffer accumulation.
Sources: kaleidux-daemon/src/main.rs:795-810
IPC and Controller Issues
The kldctl utility communicates with kaleidux-daemon via a Unix Domain Socket located at XDG_RUNTIME_DIR/kaleidux.sock or /tmp/kaleidux-{USER}.sock.
Connection Failures
Common IPC errors include:
- Connection Refused: Usually means the daemon is not running.
- Broken Pipe: Occurs if the daemon crashes or is killed during a request.
- Socket Path Errors: If the socket file exists but is stale,
kldctlmay fail to connect. The daemon attempts to remove the existing socket file on startup.
Configuration Validation
Invalid TOML in ~/.config/kaleidux/config.toml will prevent the daemon from starting or cause it to fall back to defaults. Users can validate their configuration without starting the daemon using the controller.
Validation Command:
kldctl check-config
This command checks for the existence of the file and validates the TOML structure against the expected orchestration::Config schema.
Sources: kldctl/src/main.rs:165-185, kaleidux-daemon/src/main.rs:320-325
Known Error Messages and Warnings
| Error/Warning | Cause | Resolution |
|---|---|---|
Is a directory (os error 21) | Shader loader attempted to read a directory as a .glsl file. | Check shaders/transitions/ for folder/file conflicts. |
Renderer initialization timeout | WGPU took longer than 5s to create a surface renderer. | Check GPU driver logs (dmesg). |
Broken pipe | Wayland compositor connection lost. | Restart the desktop environment or daemon. |
Image decode task panicked | Corrupt image file or out-of-memory. | Verify image integrity; check IMAGE_DECODE_SEMAPHORE limits. |
Sources: kaleidux-daemon/errors.txt:3, kaleidux-daemon/src/main.rs:445-460, kaleidux-daemon/src/main.rs:755-760
Conclusion
Most issues in Kaleidux stem from environment-specific hardware acceleration hurdles or configuration errors. By utilizing kldctl check-config for setup and monitoring the [METRICS] logs for runtime behavior, developers and users can pinpoint whether a problem resides in the GStreamer decoding phase, the WGPU rendering phase, or the IPC communication layer.