Troubleshooting and FAQ

This chapter collects fixes for common problems: start-up and graphics errors, tablets, AI service messages, ComfyUI errors, the camera notch, first-launch warnings on macOS and Windows, where SculptForge keeps its settings, how to reset the interface, and how to report a bug.

SculptForge doesn't start#

SculptForge draws with OpenGL 3.3 (core profile). Almost every GPU from the last decade supports it, but an old driver, a remote desktop session or a virtual machine without 3D acceleration may not.

1. Update your graphics driver from the GPU maker (NVIDIA, AMD, Intel) or your Linux distribution.
2. Virtual machines: turn on 3D acceleration in the VM settings.
3. Remote desktop: some remote sessions only offer an older OpenGL. Run SculptForge locally, or use a remote tool that forwards the GPU.
4. Linux: on a machine without a working GPU driver, Mesa's software renderer works (slowly): LIBGL_ALWAYS_SOFTWARE=1 sculptforge.

To see why it stopped, start it from a terminal and read the messages. It prints the OpenGL version and GPU it found at start-up (for example OpenGL 4.6 (Core Profile) Mesa 26.1.8 on ...), or the error, such as OpenGL 3.3 context creation failed or Missing OpenGL function: ....

• Linux: run sculptforge in a terminal.
• macOS: run /Applications/SculptForge.app/Contents/MacOS/SculptForge in Terminal.
• Windows: the release build has no console window; if it closes straight away, update the driver first.

First launch warnings on macOS and Windows#

The release builds aren't code-signed yet, so the operating system warns the first time.

• macOS (Gatekeeper): "SculptForge can't be opened because it is from an unidentified developer". In Finder, right-click (or Ctrl+click) SculptForge in Applications and choose Open, then Open again. macOS remembers the choice. On recent macOS versions you may instead need System Settings

• Windows (SmartScreen): "Windows protected your PC". Click More info, then Run anyway.

Download SculptForge only from the official releases page on GitHub (the website that Help > Website & documentation opens links to it).

The viewport is slow#

• Check the triangle count in the title strip (Tris). Millions of triangles on a laptop GPU are heavy; Tool > Geometry > Decimate or a lower Voxel Remesh resolution brings it down. See Subdivide, Remesh, Decimate and LODs.
• Turn off Wireframe (Shift+F) on dense meshes.
• Hide SubTools you aren't working on, or Solo the active one.
• A large Gaussian splat capture costs GPU time too: lower the count with Clean floaters, or untick Show in the Splats palette while you sculpt.
• On laptops with two GPUs, make sure SculptForge runs on the dedicated one (in the GPU maker's control panel or the operating system's graphics settings).
• Preferences > Performance: lower Antialiasing (or turn it off), keep Fast Navigation on, and look at Last stroke to see whether brushes or the graphics card take the time. Step down a subdivision level for big changes. See Performance and big meshes.
• A SubTool missing from the view with "Not enough GPU memory" in the status bar didn't fit on the graphics card: hide other SubTools or step down a level.

Pen tablets#

SculptForge reads pen pressure through the operating system's standard pen input, so most Wacom, XP-Pen, Huion and similar tablets, and pen displays, work without settings.

1. Open the Draw palette. Under Tablet it shows "Pen pressure: 0.42" once the pen has come near the tablet, or "No pen detected".
2. Pressure > strength (on by default) and Pressure > size choose what pressure controls. They are also on the top shelf.
3. A custom brush can also set its own pressure response (pressureCurve in its recipe, see Brush Lab and sharing brushes).

If no pen is detected or pressure doesn't change:

• Install or update the tablet maker's driver, then restart SculptForge.
• Windows: most drivers have a Windows Ink option. If pressure doesn't reach SculptForge, try switching it (on or off) in the tablet driver's settings for SculptForge or for all applications, then restart SculptForge.
• Linux: check that the system sees the pen as a tablet (for example in your desktop's tablet settings).
• If the cursor moves but strokes have no pressure, test in another application to see whether the driver reports pressure at all.

AI services#

Hugging Face (free image and text to 3D)#

fal.ai and Meshy#

Brush Lab#

The default Free provider uses a hosted open model with no account. If it is unreachable and Ollama runs on your computer, SculptForge uses your local model instead. "Rate limited by the provider" means too many requests in a short time: wait a few seconds. For setup of local models, see Brush Lab and sharing brushes.

No connection at all#

AI features need internet access (except a local Ollama, LM Studio or ComfyUI). Behind a company proxy or firewall, ask IT to allow the service you use: huggingface.co (and *.hf.space), fal.ai, meshy.ai, or the Pollinations.ai text endpoint for the free Brush Lab model.

ComfyUI errors#

See Image and text to 3D for setup.

The interface#

The top of the window is hidden behind the camera notch#

On MacBooks with a camera notch, SculptForge keeps the interface below the notch when it fills the screen. If the title strip or palette bar is still covered, or a plain band appears where you don't want one, change Preferences > Interface > Camera notch: Automatic (asks the system on macOS, recognises notched MacBook displays on Linux), Always reserve, or Off. F11 switches between fullscreen and a window.

Text and buttons are too small or too large#

Preferences > Interface > UI scale sets the size (Automatic, 100% to 200%). It takes effect the next time SculptForge starts, and only if you press Store Config (Ctrl+Shift+I).

My layout or shortcuts are gone after a restart#

Like ZBrush, SculptForge never saves the layout on its own. Press Store Config (Ctrl+Shift+I) to keep the current layout, shortcuts and interface preferences. See The interface.

Reset the interface#

• Preferences > Config > Restore Standard UI returns to the built-in layout and default shortcuts. Press Store Config afterwards to make it stick.
• Restore Custom UI goes back to what the last Store Config saved.
• To start completely fresh, quit SculptForge and delete ui.json (layout, shortcuts, interface preferences) and imgui.ini (positions of floating windows such as Brush Lab) from the settings folder below.

A key does nothing#

Shortcuts don't fire while you type in a text field: click the canvas first. Check the key in Help > Controls (F1), which shows every shortcut as currently assigned; a key you reassigned shows in orange in Preferences > Hotkeys, where Default shortcuts undoes every change.

Where settings live#

SculptForge keeps its settings in one folder per user:

Your library folder (projects, tools, alphas, images, splats and QuickSaves shown in the LightBox) is separate: Documents/SculptForge by default, changeable in Preferences > LightBox > Library folder.

Recovering work after a crash#

SculptForge autosaves unsaved work every 5 minutes by default (Preferences > Autosave, 0 turns it off). After a crash, the next start asks "SculptForge did not close normally last time. Restore the autosaved work?". Restore opens it as unsaved work (save it under a name); Discard deletes it. See Projects, autosave and QuickSave.

Frequently asked questions#

Can SculptForge open ZBrush files (.ZTL, .ZPR)? Not directly: they are proprietary and undocumented. Convert ZTools once in ZBrush with the free SculptForge ZTool Export plug-in, then open the .ZTL in SculptForge (see Coming from ZBrush). Or use GoZ, or export OBJ or FBX from ZBrush (see Exporting, Send to Unreal and GoZ). .ZPR projects can't be converted; open their ZTools instead.

Does it have subdivision levels, DynaMesh, ZRemesher or UVs? Voxel remesh works like DynaMesh, QRemesh like ZRemesher (with ProjectAll to bring the detail back; see Quad retopology), Auto UV unwraps any model, and Divide adds subdivision levels you can step up and down (see Subdivision levels). Dynamic on the top shelf is dynamic topology, like Sculptris Pro (see Dynamic topology).

Is it really free? Can I sell what I make? Yes and yes. SculptForge is GPL-3.0-or-later free software; the licence covers the program, not your models. The AI models have their own licences (see Image and text to 3D).

Does SculptForge send anything about me anywhere? No. There is no telemetry and no account. AI features talk only to the service you choose, when you use them.

Does it work offline? Yes. Everything except the hosted AI services works offline, and Brush Lab and image-to-3D can run on local models (Ollama, LM Studio, your own ComfyUI or generator command).

Where are my brushes? In the brushes folder in the settings folder above. Brush Lab saves every brush you make or refine there.

Report a problem#

Choose Help > Report a problem to open the issue tracker on GitHub (you need a free GitHub account). A good report includes:

1. The SculptForge version (Help > About SculptForge) and your operating system.
2. Your GPU and driver: the OpenGL ... on ... line SculptForge prints at start-up (see SculptForge doesn't start), or the GPU name from your system settings.
3. Steps to reproduce: what you did, what you expected and what happened instead.
4. The commands you ran: open the console (the backtick key, left of 1), click Copy session as script and paste it into the report. It often reproduces the problem exactly.
5. A file if the problem is with a particular model (a small .sfproj or the original file), and a screenshot for display problems.

For a security problem, don't open a public issue; follow SECURITY.md in the repository instead.

See also#

• Installing SculptForge
• The interface
• Glossary