Troubleshooting
When something in Natsura misbehaves, the fastest path to a fix is to narrow down where it broke before changing anything. This page covers the general moves, then the specific areas: FAQ, common issues, and install/upgrade. For export problems specifically, see Nanite & Unreal troubleshooting.
Read the error first
Most Natsura errors name the node and the condition. Before changing parameters:
- Note which node is flagged. A red node is where the cook failed; an orange flag is usually a warning (stale effector, missing input) that does not stop the cook.
- Read the message in the status bar or the node's error dialog (right-click the node → Errors and Warnings, or hover the error badge).
- Check the node directly upstream. Many "this node is broken" reports are actually an empty or wrong input one step up.
Where the Natsura log lives
Natsura writes one log file per Houdini session:
%APPDATA%/natsura/logs/natsura-YYYY-MM-DD-HHMMSS.log
The most recent file is the current session. When reporting a problem, attach it; it carries warnings and errors that never reach the viewport. For more detail, turn on verbose logging in Settings → Diagnostics; the About dialog has a copy-to-clipboard for the current session's log lines.
Narrow it down
- Does it happen on a fresh scene? Open a bundled example and try to reproduce. If the example works and your scene doesn't, the problem is scene-specific.
- Does it happen after a reload? Some issues only appear on first use of a node and clear after a copy-paste or scene reload (see Common Issues below). Note whether a reload fixes it; that detail helps us.
- Is it a display problem or a data problem? Toggle the node's display flag and check the geometry spreadsheet. If the data is correct but the viewport is wrong, it's a display issue, not a cook failure.
Frequently asked questions
Houdini 20.5 and Houdini 21.0, Python 3.11 production builds only, not Python 3.10, and not daily / experimental builds. See Installation.
If a feature works for some users but not others, check your tier first; some capabilities differ between Indie and the higher tiers. (The exact per-tier feature matrix is being confirmed; see Requirements for the licensing model.)
Houdini Apprentice imposes its own limits: it caps export and resolution, and some operations raise errors that don't occur on a commercial license. Natsura runs on Apprentice for learning, but Apprentice is not suitable for production export.
Contact support@natsura.com about educational use.
Use the Export Unreal Nanite Assembly node. It writes a USD scene (geometry, rig, skin weights, instance hierarchy) plus a wind.json sidecar that Unreal consumes as a Nanite Skeletal Assembly. See Working with Assemblies in Unreal for the import side, and Nanite & Unreal troubleshooting when something doesn't come across.
Often it's a refresh problem, not a broken node. A few areas (assembly decoration, trunk decoration on a fresh Grow) sometimes produce nothing on first use and clear after a small nudge. See Common Issues below.
Heavy trees re-cook on every change, and some setups currently cook more than once per change. Switch the viewport to On Mouse Up (bottom-right of Houdini), author at a lower simulation resolution, and raise it for the final result.
Natsura preferences live in a single natsura.pref file in your user data; logs live under %APPDATA%/natsura/logs/. When you update Natsura, delete the old package folder before installing the new one rather than overwriting it (see Install & Upgrade below).
Email support@natsura.com with your Houdini and Natsura versions, the log file, the exact error, and a reproducer scene if you can. The more specific, the faster we can fix it.
Common issues
"My tree disappeared" / nodes not refreshing
Several decoration setups can show nothing on first use, then work after a small nudge. This is a refresh problem, not lost data; the underlying cause is live UI not always reacting to graph changes, and fixes are in progress.
- Tree not rendering in assembly decoration. Toggle the core decoration block's bypass off and on to force a refresh.
- Assembly decoration shows nothing. It needs a linked Grow and a resource. Wire an assembly resource and link the decoration to a Grow; nudging the result (bypass toggle, or moving a branch into view) forces it to appear.
- Trunk decoration on a Grow does nothing on first use. Copy the Grow, paste it, and use the copy. (Targeted for a patch; confirm whether still needed in your version.)
Effectors not detected after wiring
- Press the refresh / detect button on the Grow to pick up a newly wired effector. Detection currently runs per effector; adding one doesn't re-scan for others.
- Removing an effector can leave stale parameters behind (an orphaned effector shows a warning flag). Remove the stale parameter or reconnect the effector.
- Renaming an effector node can create a duplicate parameter. If you see two entries, remove the stale (old-named) one.
Mappings behave unexpectedly
- Renaming a map can change the result, a map's name is used as an identifier, so renaming it can re-bind what it drives. Set the name you want before wiring it, and avoid renaming a map that's already driving parameters.
- Changing a mapping doesn't update the tree. The value can appear cached; force a re-cook (toggle the node's bypass, or nudge the source input range).
- A mapping works on one parameter but not another. Verify the source input range is set for the parameter you're actually driving.
Cooking, staleness, and performance
- Slow viewport when dragging parameters. Heavy trees re-cook on every change. Switch to On Mouse Up, author at a lower resolution, raise it for the final.
- Double or triple cooking. Stale cook triggers can cause redundant cooks. If a change doesn't seem to register, force a clean re-cook.
- Freezes / "Not responding." Lower resolution, work in stages, and save often. If a freeze looks log-related, restart Houdini with
NATSURA_LOG_DISABLED=1set to rule out the log subsystem.
Display glitches
- Node / debug colours not showing, or the debug-colour toggle not persisting between sessions.
- Bounding-box display affected by viewport lighting, a display-only artifact; the geometry is unchanged.
- Scale / layout shifts when switching scenes, viewport elements can be displaced after a scene switch.
Oversized panels
If a decorator / resource selector dropdown won't let you enter submenus, the UI panel may be too large. Shrink the panel so the submenu items become reachable.
Install & upgrade
For a clean first install, follow Installation (or Package Install) and its troubleshooting accordion. This section covers upgrades, overwrite problems, and licensing limits.
Natsura doesn't load at all
Work through the install guide's troubleshooting accordion first (wrong Houdini build, misplaced/misnamed natsura.json, backslashes in JSON paths, a conflicting package). Then confirm the package loaded: Help → About Houdini → Show Details → Packages, find natsura.json, check enable is true and there are no Natsura errors.
Upgrading Natsura
- Close Houdini.
- Delete the old Natsura folder (e.g.
Documents/natsura/houdini20.5/). - Unzip the new build into the same location.
- Start Houdini and confirm Natsura loads via the Packages report.
Your natsura.json doesn't need to change between versions unless the paths move.
Permission errors / incomplete trees after upgrading: make sure Houdini was fully closed during the upgrade; confirm Natsura isn't under a protected or cloud-synced location (C:/Program Files/..., aggressive cloud-sync folders), use Documents/natsura; older scenes may need re-opening so the upgrade pass can run.
Houdini Apprentice and Indie limits
- Apprentice caps export and resolution and raises errors on operations a commercial license allows. Fine for learning, not for production export.
- Indie has known differences from FX/commercial tiers; some features behave differently or are unavailable. If something works for a colleague but not for you, check your Houdini and Natsura tiers.
Examples and shelf missing
- A bundled example appears broken or errors when dragged in: make sure you're on a current build and did a clean install (stale examples from an overwrite are a common cause).
- The Natsura shelf is missing: confirm the package loaded (Packages report) and that you're not in a mode that hides it.
What to send support
If you're stuck, email support@natsura.com with:
- Your Houdini version (full, e.g.
20.5.684 – Py3.11) and OS. - Your Natsura version (shown in the About dialog).
- The log file for the session where it happened, and the full contents of your
natsura.jsonfor install issues. - The exact error text and the steps that reproduce it.
- A small example scene if you can share one; a reproducer is the single most useful thing you can send.
Related
- Installation · Package Install, install guides with their own troubleshooting accordions.
- Nanite & Unreal troubleshooting, export, materials, skeleton, and wind problems.
- Glossary, Natsura and botanical terms.