Troubleshooting

AppImage won't run on Linux

Solution: Make the AppImage executable:

Then run it directly:

Missing dependencies on Linux

Solution: Install required dependencies:

For Arch/CachyOS:

Varve on ChromeOS: install, launch, or file access

Solution: Install the .deb inside the ChromeOS Linux development environment and match your architecture (uname -m). ChromeOS does not expose GPU acceleration to Linux apps, printing needs CUPS inside the container, and files kept only in the container are deleted if the Linux environment is removed — keep projects in a shared My files/Drive folder. The full walkthrough is in Varve on ChromeOS.

macOS says the app is damaged, or blocks the first launch

0.5.0: that release has no bundle-wide signature, so a browser-downloaded copy shows “Varve is damaged and can’t be opened” with no Open Anyway option. Right-click > Open also stopped working in macOS 15. After dragging Varve to Applications, run:

That command removes the browser-download quarantine flag so Gatekeeper will open the app. Do not disable Gatekeeper.

Later releases: after the first launch attempt, open System Settings > Privacy & Security and choose Open Anyway. Do not disable Gatekeeper.

Windows SmartScreen or Smart App Control blocks the installer

SmartScreen: choose More info, then Run anyway — after verifying the SHA-256 checksum on the download page.

Windows 11 Smart App Control can block unsigned apps with no override. If that happens, use the browser versioninstead of turning the protection off.

WebGPU is unavailable, or GPU-accelerated effects are slow

Symptom: the capability report shows WebGPU unavailable or failed, and effects such as blur or large image adjustments feel slower than expected.

Likely causes: the device or driver does not expose a usable WebGPU adapter, the GPU process is unavailable, or the page is running in a context where GPU access is restricted. On ChromeOS this is expected on some devices and versions; the exact driver state is uncertain without the capability report.

Safe checks: open Settings → Performance → Platform capability report and read the graphics result; check chrome://gpu for WebGPU/Canvas status. Do not enable browser flags to force an unsupported path.

Bounded action: continue with the Canvas2D path, which is authoritative. Reduce simultaneous large effects and close other tabs. If you were testing a specific document, try it in a new tab without other media playing.

Expected result: editing remains correct; heavy effects render more slowly through the CPU path, and nothing in the document changes.

If it still fails: report it with the capability report JSON, Chrome/ChromeOS version, and device model. Do not treat the device's advertised NPU as usable; Varve does not use it.

The status bar reports a lost GPU while you were editing

Symptom: with the WebGPU preference enabled, the status shows “GPU lost · Canvas2D” after a driver reset, system sleep or resume, or a GPU process crash.

What happens automatically: Canvas2D keeps drawing immediately, so nothing on screen disappears and the document is never at risk. Varve then tries to rebuild the WebGPU device by itself (two bounded attempts); when one succeeds the status returns to the live renderer label without a reload.

Bounded action: if the status settles on the lost-Canvas2D message, save your work and reload the tab to retry WebGPU from a clean state. If loss repeats in the same session, prefer leaving the WebGPU preference off for that device and report the driver and browser version.

Expected result: edits, history, and exports are identical whichever path served the pixels; the loss changes performance, never content.

Heavy operations are slow, stall, or fail

Symptom: background removal, upscaling, image tracing, large imports, or long pans take a long time or end in an error.

Likely causes: memory pressure from several large images at once, browser WASM running single-threaded on the demo host, a very large source image, or a model operation competing with foreground editing. The browser may also be about to discard the tab.

Safe checks: watch the Storage & Offline estimate and the capability report; confirm the document is saved; check Chrome Task Manager for the tab's memory. Save first — recovery copies are a safety net, not a destination.

Bounded action: run one heavy operation at a time, close unused tabs, and prefer smaller source images. Wait for an operation to finish or cancel it from its dialog before starting another.

Expected result: the operation completes or reports a bounded error; the document stays editable and the last save is untouched.

If it still fails: note the operation, source image size in pixels, and the capability report; report it. Attach no private design content — describe the document instead.

The browser reports low storage or a write fails

Symptom: a save or recovery write fails with a quota message, or the storage estimate is nearly full.

Likely causes: the origin's storage quota is exhausted (the largest contributors are offline application copies, recovery copies, and imported images), or the device itself is low on free space. Quota derives from total disk size and is an estimate, not a guarantee.

Safe checks: open Settings → Storage & Offline; note the estimate and how many recovery copies exist. Make sure any unsaved document is exported through Save As first.

Bounded action: clear offline app copies only (the control is labeled and prefix-gated); remove downloads you no longer need through Chrome's download manager. Never delete recovery copies while a document has unsaved edits, and never delete browser-wide site data to "clean up" without exporting first.

Expected result: new writes succeed; saved documents, recovery copies, and installed-app state are preserved except the disposable offline copy you chose to clear.

If it still fails: report the estimate, the exact error text, and free disk space. If the device itself is full, free space in ChromeOS Files or remove unused Android/Linux content — with a backup first.

A document opens with the wrong font, or text looks different

Symptom: a font is substituted, text metrics shift, or a document warns about missing fonts.

Likely causes: the document uses a font that is not installed in this environment. The browser uses bundled fonts plus any local fonts the browser exposes; the Linux application sees only the container's fontconfig set, not the host's. Which fonts a given document needs is reported by the missing-font control.

Safe checks: open the font panel and read the missing-font list; compare on the machine where the document was created.

Bounded action: install the missing font in the environment doing the rendering (browser: add the font file through the font controls where offered; Linux: copy the font into ~/.local/share/fonts and run fc-cache -f), then reopen the document.

Expected result: the substituted font is replaced; if the face is unavailable, the fallback is documented instead of silently different.

If it still fails: report the font name, format, and where it was installed. Do not upload a licensed font to a public issue.

An optional model download is blocked or fails

Symptom: an AI feature reports that its model could not be downloaded, or the download stalls.

Likely causes: network restrictions, a proxy or captive portal, insufficient free space, or an interrupted large download. Models are large (hundreds of megabytes to roughly a gigabyte) and are never bundled with core editing.

Safe checks: confirm normal web browsing works in the same tab, check Storage & Offline, and read the model dialog's byte figures for download versus estimated working memory.

Bounded action: retry on an unmetered connection with enough free space; download one model at a time. Core editing does not need any model — continue without it.

Expected result: the feature reports a clear unavailable state and editing continues unaffected.

If it still fails: report the model name, the error, and available space. Do not disable browser security controls or add untrusted certificate exceptions to make a download work.

Linux is missing on the Chromebook

Symptom: "Linux development environment" is absent or disabled in Settings, or the Terminal app is unavailable.

Likely causes: the model does not support Linux, or a work/school administrator has turned it off. This is a device policy state, not a Varve setting.

Safe checks: confirm the Settings path About ChromeOS → Developers; on a managed device, check the organization's policy summary if your administrator provides one.

Bounded action: use the browser route at varve.studio/try/, which needs no Linux. If you need Linux for other reasons, contact your administrator.

Expected result: the browser route remains fully available; the Linux route stays unavailable by design.

If it still fails: ask the administrator. Do not attempt Developer Mode, firmware changes, or policy bypasses — this project neither documents nor supports them.

The Linux package installs the wrong architecture or refuses to install

Symptom: apt reports an architecture mismatch, or the package installs but does not launch.

Likely causes: the downloaded file does not match the device (ARM64 Chromebooks need aarch64; Intel/AMD need x86_64), or the container's Debian release is older than the supported floor (glibc 2.35, Debian 12+).

Safe checks: run uname -m and dpkg --print-architecture, and compare them with the file name and dpkg-deb --info output; run cat /etc/os-release for the container release.

Bounded action: download the matching package from the release page and install it with sudo apt install ./Varve-<version>-linux-<arch>.deb. If the container is too old, update it with sudo apt update && sudo apt dist-upgrade and retry. Do not force-install with --force-all/--force-depends.

Expected result: the correct package installs and launches from the Launcher or varve-desktop.

If it still fails: report the two architecture outputs, /etc/os-release, the exact file name, and the error. See Varve on ChromeOS.

A Linux launch shows a blank window or missing libraries

Symptom: the app opens an empty window, exits immediately, or apt reports unmet dependencies.

Likely causes: the WebKitGTK renderer failed, a declared dependency is missing from the container, or the graphics path is unavailable (ChromeOS does not provide hardware acceleration to Linux apps).

Safe checks: run varve-desktop from the Terminal and read the error; check that a WebKit web process exists with pgrep -af WebKitWebProcess; confirm dependencies with sudo apt install ./Varve-*.deb rather than dpkg -i.

Bounded action: retry once with WEBKIT_DISABLE_DMABUF_RENDERER=1 varve-desktop as a diagnostic. This is a workaround, not a fix: unset it afterwards and report whether it changed anything. Never disable sandboxing or system security.

Expected result: a window renders through the software path, or the terminal error identifies the missing piece.

If it still fails: report the terminal output, container release, and whether the workaround helped. Use the browser route in the meantime.

A dialog or the on-screen keyboard hides what I am editing

Symptom: a dialog opens partly off-screen, or the on-screen keyboard covers the caret or the dialog's buttons.

Likely causes: a viewport height the layout has not seen yet (rotation, split-screen, or keyboard animation), or a zoom level that pushes a fixed-position surface beyond the visible area.

Safe checks: rotate to landscape or exit split-screen and reopen the dialog; check the browser zoom is at 100%.

Bounded action: dismiss and refocus the field so ChromeOS scrolls it back into view; close and reopen the dialog once. Do not use browser fullscreen as a permanent workaround for a layout bug.

Expected result: the caret and commit/cancel controls are visible; closing the keyboard restores the previous canvas size.

If it still fails: report the exact viewport size, orientation, keyboard layout, and a screenshot with no private content. This is a known class of device-only issues and remains on the hardware checklist.

Printing or colour-managed export is unavailable

Symptom: no printers are listed in the Linux app, or print-production options (PDF/X, CMYK, ICC) are missing in the browser.

Likely causes: print production is a desktop-only feature and is not in the browser build; inside ChromeOS Linux, printing depends on CUPS, which is commonly absent, and ICC profiles are container-local.

Safe checks: check the Export dialog for PDF export; in the Linux app, check whether CUPS is present; in the browser, use the browser's print dialog after exporting.

Bounded action: export a PDF from Varve and print it from ChromeOS (Files or the browser) instead of printing from the Linux app. Keep colour-managed production work on a supported desktop.

Expected result: a print-ready PDF file; colour management remains an explicit desktop workflow.

If it still fails: report the export format and where printing failed. Do not install third-party CUPS repositories just to enable this route.

Installing, updating, or removing the browser app misbehaves

Symptom: no install option appears, the app opens as a tab, an update notice does not apply, or uninstalling removed data unexpectedly.

Likely causes: install criteria not met (unsupported browser, private window, or policy), the page not being reloaded after an update, or choosing "delete data" during uninstall (or clearing browsing data) which removes documents and recovery copies.

Safe checks: confirm the address bar shows the Varve origin over HTTPS; check chrome://apps for the installed entry; export any unsaved work before removing anything.

Bounded action: reload once to pick up a waiting update. If an administrator blocks installation, use the tab instead — the behavior is identical; the browser guide covers the exact menus.

Expected result: the app opens in its own window, updates only after you accept, and uninstall without deleting data leaves documents intact.

If it still fails: report the browser version, ChromeOS version, and whether the device is managed. Never clear all browser data as a first response.

Collecting safe diagnostics for a report

Do: include the Varve version, Chrome and ChromeOS versions (chrome://version), the emulated or real viewport size, the platform capability report JSON from Settings → Performance, the exact error text, and steps to reproduce with a non-private sample.

Do not: attach real design documents, font files you cannot redistribute, personal file paths, account details, or any secrets. Strip or replace private content in screenshots.

Escalation: report through Report an Issue or GitHub Discussions when the issue is reproducible and not a known-limitations item. Mention clearly whether the result came from emulation or real hardware.

Varve is slow or laggy

Solution:

• Check if you have many objects on canvas (viewport culling helps, but extreme counts may slow down)
• Ensure your GPU drivers are up to date
• Close other applications to free memory
• Check if you're running on Wayland (primary dev environment) vs X11

Canvas rendering is slow

Solution: Browser and desktop builds use different runtimes, and performance varies with your document, renderer, display, and device. Open Settings → Performance → Platform capability report to see the active backend and include the report with a representative document when asking for help. See the lower-memory performance guide for device-specific behavior.

Rich text not rendering correctly

Solution: Rich-text source indexing, grapheme-safe transactions, and selected mixed formatting controls are available, but the canonical shaped layout is still being connected to every renderer and export path. Keep complex per-span compositions short while testing and verify the final export. See the Known Issues and Typography pages for current status.

Collaboration features not working

Solution: Collaboration features are UI scaffolding only with no transport or wire protocol. Real-time collaboration is planned for future development.

Print export not showing bleed

Solution: Print bleed and trim guides are available in the current print workflow, but exported trim/bleed geometry remains the final authority. If guides appear stale after changing page settings, reopen the page or export again and verify the PDF.

Touch gestures don't do what I expect in the browser demo

Solution: One finger operates the active tool by default, while two fingers cancel only the provisional first-pointer action and then pan or pinch-zoom the canvas. Change the reversible choice in Settings > Drawing inputif one-finger viewport navigation is more useful. After a pinch, lift both fingers and start a fresh contact before drawing; the remaining finger cannot silently resume a stroke. If the wrong tool is active, pick one from the palette or press its shortcut. Long-press a stack of overlapping layers for the deep-selection menu (the touch equivalent of right-click). On a touchscreen laptop both the touchscreen and the trackpad stay active — a trackpad two-finger scroll pans the canvas, and a trackpad pinch zooms it.

A pen stroke is not pressure-sensitive or a finger interrupts it

Solution: Open Settings > Drawing input and confirm pressure interpretation is enabled. A default or missing pressure sample is not proof of a working pressure sensor, so Varve keeps a stable constant response as the fallback. During an active pen stroke, foreign touch and compatibility contacts are ignored rather than merged into the stroke. Browser emulation does not prove physical USI pressure, tilt, eraser, hover, or palm rejection; include the ChromeOS version, device, and whether this happened in the browser/PWA or Linux desktop route when reporting it.

A keyboard shortcut does nothing on a Chromebook

Solution: ChromeOS reserves some combinations before the page sees them. Ctrl+1…8 switches browser tabs, Ctrl+T /Ctrl+W / Ctrl+N manage tabs and windows,Ctrl+Shift+I / Ctrl+Shift+J open Developer Tools;Ctrl+Shift+B toggles the bookmarks bar; Ctrl+Shift+M opens Chrome profile switching; Ctrl+Shift++ / Ctrl+Shift+- / Ctrl+Shift+0changes the screen resolution. Use the menu, command palette, toolbar, or status bar for those actions. Varve's six workspace switches use Ctrl+Shift+1…6; Logo Tools and the shared Code panel use Ctrl+Shift+7 and Ctrl+Shift+8. Use the 8 action or View > Panels > Code Panel when the browser reserves Ctrl+Shift+J. The Logo Tools toggle is Ctrl+Alt+Shift+L; it switches to Design when opening from another workspace. See the keyboard shortcut reference for workspace order and browser-specific alternatives. Use Varve's View menu for Inspector and Minimap when Chrome reserves their desktop chords. Zoom keys are matched by physical key position, so they behave the same on French and English Chromebook keyboards. On macOS, use Command+Shift with the same numbers.

The on-screen keyboard covers the editor

Solution: Varve uses keyboard bounds when the browser exposes them and visible-viewport geometry as a fallback. If a field or its Done/Cancel controls are still covered, dismiss and refocus the field so the operating system can scroll it into view. Floating keyboard placement varies by operating system and has not been certified on physical tablet hardware; report the browser, device, viewport, and whether the keyboard is docked or floating.

I need modifier keys or layer actions without a keyboard

Solution: open Editing controls from the floating toolbar. Constrain, From centre, and Bypass snap stay latched until you turn them off; Deep select arms the next canvas tap. The same surface offers Duplicate, alignment, and layer-order actions. Use Appearance > Mirror tablet controls to move the panel launchers across the screen.

Back closes the wrong surface or leaves the editor

Expected behavior: browser Back dismisses the topmost eligible open Varve dialog or menu before following an in-app route. Tooltips and surfaces that cannot safely close are skipped. ChromeOS controls its system edge gesture, so if that gesture bypasses the app, use the visible close or Back control and report the browser/device route; browser emulation does not certify system-gesture dispatch.

Varve crashes on startup

Solution:

• Check system requirements (4GB RAM minimum, 8GB recommended)
• Ensure you're using a supported OS version
• Check if other applications are using excessive memory
• Report the issue with your OS, version, and crash logs

Specific tool crashes

Solution: Report the issue with steps to reproduce, your OS, and Varve version. Include any error messages or crash logs if available.