Troubleshooting¶

Common problems and fixes. If your issue is not listed, check the Debug Log for diagnostic information, then contact the Kanzi Support Portal at support.rightware.com.

Connection issues¶

“Searching” never finishes¶

Check the bridge server is running: open http://localhost:3847/status in a browser. You should see JSON.
Restart the Kanzi Studio plugin (close and reopen the panel). A full Kanzi Studio restart is usually only required after a plugin update.
If a firewall blocks localhost:3847, pause the firewall and retry.
If the bridge server has crashed, check the Debug Log for [Bridge] errors.

Empty pending list after Connect¶

Figma plugin shows green but Kanzi Studio doesn’t see the pending entry → the bridge server’s pending list is stale. Restart the Kanzi Studio plugin (close and reopen the panel from Kanzi Studio’s top bar).
Online mode: the tunnel URL might have expired. Disconnect on both sides and reconnect to generate a fresh URL.

Reconnect fails¶

Bindings are torn down when either side disconnects, so reconnect should always land on a fresh pending entry. If you still hit this, the binding is stale — file a bug with Debug Log contents.

“Already connected” error¶

The binding may be stale from a partial disconnect. Restart both sides and re-pair.

Jump-to-Kanzi broken after reconnect¶

The binding is stale — restart both sides and re-pair.

Panel / window issues¶

Panel opens off-screen¶

Kanzi Figma Importer remembers the size and position of its floating window between Kanzi Studio sessions. After a monitor change (laptop undocked, secondary monitor disconnected, resolution change) the saved coordinates can land outside the visible work area.

Recent plugin builds detect this automatically and snap the window back to the primary work area on the next open. If the window still opens off-screen, reset the saved geometry manually:

Close Kanzi Studio.
Delete %LOCALAPPDATA%\FigmaImporter\plugin-window.json.
Start Kanzi Studio again — the panel opens at the Kanzi Studio default position.

Don’t drag the Debug Log splitter¶

Dragging the divider between the main panel and the docked Debug Log can crash Kanzi Studio and lose unsaved work. Keep the default width, and save your project before opening the Debug Log.

Font issues¶

Font not auto-resolving¶

The font might not exist in the Google / Bunny / Fontsource catalogs (Enterprise or commercial fonts).
Workaround: drop the TTF file into <project>/Fonts/ and re-import. Kanzi Figma Importer picks it up via the local-folder fallback.
Alternative: use the Text as SDF option — flatten glyphs to vectors so the font isn’t needed at runtime.

Wrong font weight or style¶

Check the Figma font has the variant you’re requesting (some fonts only ship Regular).
Look at the Debug Log [FontCheck] lines to see which variant the resolver picked.

Import and re-import issues¶

“Searching” stuck during import¶

Click the button to cancel. The panel returns to Idle.

“kzProjectionCameraWorldMatrix” dialog¶

Kanzi Figma Importer dismisses this modal automatically in the background so Shape imports run uninterrupted. If the dialog appears, click Yes. The action is safe.

Duplicate shape on re-import¶

The figmaId tag on the existing node may have been lost. Check the Description field of the original node — if it’s missing the figma-node-id: line, Kanzi Figma Importer can’t match it.
Workaround: delete the duplicate and re-import. The new node gets a fresh figmaId.

Duplicate prefab after wrapper rename¶

Renaming a wrapper prefab and then re-transferring can create a duplicate (for example, Topbar and Topbar_1). Workaround: delete the duplicate after the re-transfer.

Same conflict on every re-import¶

This is by design. Until you explicitly choose Override, the diff keeps firing. Click Override (or Keep user edits in the bulk panel) to advance the baseline. See Query mode.

“Same name PNG exists” after delete¶

Cache or index in Kanzi Studio not refreshed. Save and reopen the project; or click Overwrite when prompted.

Shape and rendering issues¶

Sharp corners look rounded¶

SDF rendering limitation. Workarounds:

Use the rectangle or ellipse parametric shaders (sharp by default) where possible.
For vector shapes, accept the rounding or bake to image with [KZ_BAK].

Open shapes clipped at edges¶

SDF padding limitation. Partial fix shipped (dynamic range + padding). For perfect fidelity, bake to image.

Vector texture clipped at corners¶

Same as above. Increase the SDFScale slider in the Inspector if available, or bake.

Gradient position off vs Figma¶

Known minor drift. Needs broader testing across all gradient types before a final fix.

Online mode issues¶

Tunnel URL doesn’t work¶

The URL might have a typo. Copy the URL directly from the Kanzi Studio plugin status bar.
Confirm the Online mode switch in the Figma plugin is on before pasting the Access Key.
The Cloudflare quick tunnel is ephemeral. If the Kanzi Studio plugin or the bridge server stops, generate a new tunnel by reconnecting from Kanzi Studio.

Paste Access Key button inert¶

Figma CSP blocks navigator.clipboard.readText() and execCommand('paste'). Use Ctrl+V in the field directly.

Online connection rejected¶

Kanzi Figma Importer rejects unknown or stale file keys on accept. Disconnect on both sides and re-pair from scratch.

`[KZ_BAK]` and `[KZ_BAK_TINT]` issues¶

`[KZ_BAK_TINT]` placeholders look white¶

The TintColor default is transparent, so untinted placeholders pass the mask texture through unchanged. If a placeholder still flattens to white, check that its TintColor override has not been set to opaque white by hand.

`[KZ_BAK]` instances show wrong texture¶

Check the per-placeholder Texture override in the Kanzi Studio Inspector. It should be <W>.Image pointing to the per-instance texture. If the override is missing, the import did not tag the placeholder correctly. Re-import.

Bug reporting¶

When filing a bug:

Reproduce.
Click Copy All in the Debug Log → paste into the report.
Attach the .kzproj if the issue involves metadata or library state.
Include the Figma file URL (or a minimal reproduction file) if it’s a Figma-side issue.