Troubleshooting
Messages appear as toasts in the corner (color-coded info, success, warning or error) or as centered dialogs. This is the current user-facing set.
Project and file messages
Section titled “Project and file messages”| Message | Meaning |
|---|---|
Project saved | A manual save succeeded. |
Save failed - your work is not saved | The write to disk failed. Your work is still in memory: try Save again, or use Export Diagnostics… and save elsewhere. Back to Hub aborts rather than navigating away when this happens. |
Autosaved | The five-minute autosave timer fired and wrote the .autosave companion. See Autosave & Recovery. |
Failed to load project: … | The archive could not be read: wrong format version, corruption, or a missing internal file. |
Project not found - it may have been moved or deleted. | A recent-projects entry or an opened file no longer exists on disk. The entry is removed from the list. |
Could not create the project. Please try again. | Writing the new blank project archive failed. |
Could not delete "<name>" - make sure it isn't open elsewhere. | The OS refused to delete the file, usually because another program has it open. |
Deleted "<name>". | The project file was permanently deleted. |
Saved preferences could not be read - using defaults. | Your settings file was unreadable. Everything reverts to defaults; your projects are unaffected. |
Asset, node and export messages
Section titled “Asset, node and export messages”| Message | Meaning |
|---|---|
Open a project first. | You tried to import an asset with no project open. |
Asset imported. | The file was embedded into the project. |
Failed to import asset: … | The file could not be read or embedded. |
Add a PBR Output, Trim Sheet, or Custom Output node to export textures | The export shortcut found no output node in the graph. See Exporting. |
Exported N textures, optionally (N not ready) | Export finished. “Not ready” channels are ones whose textures had not finished evaluating. |
Nothing exported - connected textures are still rendering | Nothing was written because every planned channel was still evaluating. Wait for the graph to settle and export again. |
Nothing exported - connect textures to this node first | Nothing was written because the output node has nothing wired into it. |
Export failed - no files were written | Nothing could be written to the chosen folder. |
Exported <node> as .surfacenode / Export failed - no file was written | Single-node package export. See Sharing Nodes. |
Could not import .surfacenode - file is invalid | The package could not be read. |
Unknown node type "…" - cannot place | The package references a node type this build does not have. |
N connections dropped - the port it was wired to no longer exists | Editing a custom shader’s inputs removed a port that had a wire attached. |
Not a TrueType/OpenType font / Could not read the font file | The file chosen in the Text node’s font picker is not a usable font. |
Could not load HDRI - is it a Radiance .hdr? / Environment loaded | 3D preview environment import. See 3D Preview. |
Exported 4K preview to … / 4K preview export failed | 3D preview beauty-shot export. |
Added N tags from this project: … | Opening someone else’s project added tags you did not have to your local vocabulary. |
This project was authored above 4096 × 4096 and has been reduced to fit this device. | iPad and Android only. An 8K project was clamped to the handheld ceiling on open, and marked as changed. See Project & File Formats. |
This material was authored above 4096 × 4096 and has been reduced to fit this device. | The same clamp, applied when you switch to another material inside the project. |
Memory messages
Section titled “Memory messages”| Message | Meaning |
|---|---|
High memory use - previews may reduce quality | Texture use reached 80% of the memory budget. Nothing has been dropped yet. |
Reduced preview quality to stay within memory | Textures were evicted, the OS asked for memory back, or the app has used 90% of its iOS memory allowance. |
Both fire once per episode rather than repeatedly. See Performance & Memory.
Settings and diagnostics messages
Section titled “Settings and diagnostics messages”| Message | Meaning |
|---|---|
Diagnostics exported / Diagnostics export failed: … | Settings → General → Export Diagnostics… |
Crash report saved to … / No crash report to export. | The hub’s crash notice and the debug page’s export button. |
Theme exported. / Custom theme saved and applied. | Appearance page. |
Fill in all color fields before saving. | A theme token’s hex field is empty or invalid. |
Could not import theme - the file may be invalid. | The .surfacetheme could not be read. |
"<name>" matches a built-in theme name - saving anyway. | A naming collision warning, not an error. |
GPU selection is unavailable on this device. | Adapters could not be enumerated, usually no native library present. |
Token copied / Claude Code command copied / Client configuration copied | MCP Server page clipboard actions. |
Extension saved. Drag it into Claude Desktop → Settings → Extensions, then paste the token. | The .mcpb bundle was written. |
Could not save the extension: … | Writing the .mcpb failed. |
Confirmation dialogs
Section titled “Confirmation dialogs”| Dialog | When |
|---|---|
| Delete project? “This permanently deletes … This action cannot be undone.” | Deleting a project file from the hub. |
| Delete shelf? | Deleting a project shelf. |
| Remove from shelf? | Removing a project from a user shelf. |
| Reset all shortcuts? “This restores every keyboard shortcut to its default binding. This action cannot be undone.” | Reset All Shortcuts in Settings. |
| Close Minimap “Hide the canvas minimap? You can show it again from the toolbar or with Ctrl+M.” | Long-pressing the minimap title bar. |
The crash notice is not one of these. It is a toast with an Export… button, it names whether the crash was the previous session or an earlier one, and once it slides past it never asks about that crash again. See Autosave & Recovery.
Editor state messages
Section titled “Editor state messages”| Message | Meaning |
|---|---|
Expand to full screen to start editing. | iPad only. The app window is not full screen. Editing is blocked until it is. |
No Jump Nodes on canvas. | The Jump Node list is empty. |
No matches | The toolbar search found neither a node nor a manual article. See Interface Tour. |
Select a node to edit its parameters | The Properties panel with nothing selected. |
The manual is missing or incomplete
Section titled “The manual is missing or incomplete”The manual is not shipped inside the application. It is downloaded from surfacelabs.app the first time the app is online and cached on disk, after which it works fully offline and updates itself without an app update.
- On a device that has never been online there is no manual yet. Search offers no article results, and an article opened by a cross-link reads “This article hasn’t been downloaded yet - the manual syncs from surfacelabs.app the next time you’re online.”
- Every network failure - offline, a 404, a 500, a timeout, a bad response - is handled the same way: keep the last good copy. No documentation error is ever shown, because there is nothing you could do about it. The next launch with a connection fills in whatever is missing.
- Illustrations are fetched per image as you open the articles that use them, so an article read for the first time offline shows its prose without its pictures. Settings → Library → Documentation can pre-fetch them all, and reports what is on disk. See Settings.
The 3D preview stopped
Section titled “The 3D preview stopped”While the native renderer is coming up, the panel reads
Starting native renderer….
If it cannot start, the panel shows 3D renderer stopped, the
underlying failure, and a Restart Renderer button that tears the native
core down and rebuilds it from scratch. A failed start is retried
automatically a few times first, because it is usually a create racing a
teardown; the button is for a core that is genuinely wedged.
The preview survives a discrete GPU dropping out of the adapter list - Remote Desktop, or a driver reset mid-session. The presentation bridge is matched to the same adapter the renderer picked, so it falls back to the integrated GPU and keeps working instead of failing with an interop error.
If the preview misbehaves on one particular Windows machine, try Settings → General → Graphics Backend → Vulkan. It is an escape hatch for a DirectX 12 driver bug, not a faster path. See Settings.
Custom shader quarantine
Section titled “Custom shader quarantine”A shader whose loop never exits stalls the GPU until the operating system resets the driver. Every new shader source is therefore trial-run at a small size first. A source that fails the trial, or that takes the app down with it, is quarantined: it stops rendering, and the editor shows a banner with a Run anyway button. Editing the source in any way starts a fresh trial. Use Run anyway only when you know the loop bounds are sound.
See Shader Editor & Diagnostics for the full diagnostics workflow.