Troubleshooting and FAQ

Installing

Windows says "Windows protected your PC". The installer isn't code-signed yet. Click More info ▸ Run anyway. The one-line installer verifies the download against the release checksums.

macOS says Whittle "can't be opened" or "is damaged". The app isn't notarized by Apple yet. Right-click Whittle in Applications ▸ Open ▸ Open. On macOS 15+, try opening it once, then System Settings ▸ Privacy & Security ▸ Open Anyway. Or install with the one-line installer, which avoids the warning. If macOS still says "damaged": xattr -dr com.apple.quarantine /Applications/Whittle.app.

Linux: the AppImage does nothing. Install FUSE 2: sudo apt install libfuse2t64 (Ubuntu 24.04+), sudo apt install libfuse2 (older Debian/Ubuntu), sudo dnf install fuse-libs (Fedora). Or use the .deb/.rpm.

Linux: the window is blank or the app crashes on start (NVIDIA, some VMs). Start it with WEBKIT_DISABLE_DMABUF_RENDERER=1 whittle-desktop (AppImage: WEBKIT_DISABLE_DMABUF_RENDERER=1 ~/.local/bin/whittle).

curl: command not found. Install curl first: sudo apt install curl, sudo dnf install curl or apk add curl.

Using Whittle

The status bar says "Engine error" or the model never builds. Whittle needs WebAssembly and WebGL 2. Update your browser (or the desktop app), turn off extensions that block scripts for the Whittle site, and reload. On a server behind a proxy, make sure the proxy doesn't strip or replace Whittle's Content-Security-Policy headers. The geometry engine needs them.

The 3D view is black or very slow. Your graphics driver may be blocking WebGL. In Chrome or Edge, check chrome://gpu; enabling hardware acceleration in the browser's settings usually fixes it. Very large imported STL meshes are slow; import STEP instead where possible.

A feature turned red. Hover it in the timeline or open it: the message says what went wrong and often offers a one-click fix, such as "Use 9.8 mm". See Errors and Warnings.

My fillet moved to the wrong edge after I changed a sketch. Whittle re-finds edges by their geometry. When it isn't sure, it shows a warning; open the fillet and re-pick the edges.

I closed Whittle without saving. Open it again: the start screen offers Continue where you left off.

I saved over something I needed. Open Export ▸ Version history and restore an earlier version. See Version History.

Can I open my design in Fusion 360, SolidWorks, Onshape or FreeCAD? Export STEP. It keeps exact geometry. The parametric history (timeline) stays in Whittle.

Which format for 3D printing? 3MF (recommended; keeps units) or STL. Both work with Bambu Studio, PrusaSlicer, OrcaSlicer and Cura.

Laser cutting, vinyl cutting, CNC routing? Open the sketch and use Export sketch as SVG or DXF; they're true to size in millimetres. For 3D CNC/CAM, export STEP.

Can I import a logo? Yes: in a sketch, Special ▸ Import SVG. Closed shapes become sketch outlines you can extrude, emboss or cut. Convert text to paths in your drawing program first.

Server

The page shows the sign-in screen again after every reload. Using http:// with WHITTLE_PUBLIC_URL set to an https:// address (or WHITTLE_SECURE_COOKIES=true) makes the browser drop the cookie. Open Whittle at its https:// address, or fix the setting.

Saving a very large design fails. Raise WHITTLE_MAX_UPLOAD_MB, and your reverse proxy's limit (nginx: client_max_body_size).

"This design was saved somewhere else since you opened it". It was saved from another tab or computer after you opened it. Choose Save anyway (the other version stays in the history) or cancel and reopen it from your library.

The service doesn't start. journalctl -u whittle -n 50 (Alpine: tail -n 50 /var/log/whittle.log). A wrong setting is named in the error. "Address in use" means another program uses port 8080: change WHITTLE_BIND.

Can't reach it from another computer. Check it listens on all interfaces (WHITTLE_BIND=0.0.0.0:8080), and open the port in the firewall: sudo ufw allow 8080/tcp, or sudo firewall-cmd --add-port=8080/tcp --permanent && sudo firewall-cmd --reload.

Forgot the admin password. sudo whittle-server user passwd <name>. See Users and Administration.

About

Is it free? Yes, open source under the MPL-2.0 license, for personal and commercial use.

Does it send my designs anywhere? No. The desktop app works fully offline. A server only stores designs on the machine you run it on. There is no telemetry.

What's coming? Sketch constraints, assemblies, 2D drawings, sweep, threads and sheet metal are on the roadmap.

Found a bug or have an idea? Open an issue. Include your system, the Whittle version (the release you installed; on a server, /api/config shows it) and, if you can, the .whittle file.