Skip to main content

Troubleshooting

Start here:

./gradlew kanvasDoctor
./gradlew kanvasCompatibility
Debug from the outside in

Fix environment and toolchain failures before investigating renderer output. The useful order is Doctor → compatibility → renderer audit → strict mode → backend-specific debugging.

Kanvas cannot find my app module​

Set it explicitly:

kanvas {
    target = ":desktop"
}

Use ./gradlew projects to inspect project paths.

Native runtime will not build​

Check:

  • JDK 17+
  • CMake
  • Ninja or Make
  • a native compiler/toolchain
  • host graphics/runtime development packages

macOS​

xcode-select -p

Linux​

Check X11 development packages, the Vulkan loader/runtime, and a working Vulkan driver.

Windows​

Confirm the expected MinGW-w64/native toolchain is installed and available.

App starts but rendering is wrong​

Use:

kanvas {
    backend = "auto"
    audit = true
    capture = true
}

Then inspect:

build/kanvas/renderer-audit.log
A visible window is not enough

The application can launch while Kanvas fails to own the final frame. The audit log is the quickest way to verify whether the expected Skiko transforms were installed and takeover was armed.

For renderer development:

kanvas {
    strictRenderer = true
}
Strict mode may terminate the run

That is expected when Kanvas encounters a renderer path it cannot safely claim. Strict mode is designed to expose false-positive “it rendered” results.

Bug-report details​

OS:
Architecture:
GPU:
Backend:
JDK:
Gradle:
Kotlin:
Compose Desktop:
Skiko:
Kanvas version:

Project issues: Yuries-Public-Stuff/Kanvas