Terrain Troubleshooting¶
| Symptom | Checks and action |
|---|---|
| Pro Terrain is missing | Confirm the add-on is enabled and check for startup errors. Open the 3D Viewport sidebar with N. See Installation. |
| There is no graph to edit | Click Add Terrain, select its row and open the Pro Terrain editor. Confirm the selected entry has a Graph assigned. |
| The wrong terrain is visible | The sidebar's active row selects the displayed terrain. Select the intended row and check its Graph. Size, preview and lighting settings are shared by the scene. |
| The preview remains unchanged after editing | With Auto Update off, click Refresh Terrain Preview. With it on, check build status: the previous result remains visible until the new job finishes. Confirm the edited branch reaches Terrain Output. |
| A flat gray plane replaces the terrain | Read the error in the sidebar and on the marked node. Check required sockets, source files, drawing objects and muted nodes. Correct the error and refresh if Auto Update is off. The flat plane is an error display, not an exported terrain result. |
| GPU Preview is unavailable | On Linux and Windows, select Vulkan in Blender's Preferences and restart. On macOS, use Metal. See Installation if the preview remains unavailable. |
| Terrain reports a GPU timeout | Retry the build. If it recurs, check the GPU driver and try a lower resolution or a simpler graph. Total build time is unrestricted, but an individual GPU operation can fail if it does not complete within 60 seconds. |
| The geometry preview looks less detailed | Heightfield Geometry is limited to a bounded preview mesh. Use GPU Preview for 1K through 4K inspection, and Bake Terrain Mesh for final geometry. |
| A drawing does not affect the terrain | Check Drawing Field's Drawing object and the links to the terrain operation. Closed Area needs closed contours. Use Poly or Bezier curves; Curve modifiers are not evaluated. See Drawing Terrain. |
| A river runs uphill or a road grade is unexpected | Check the drawing's direction, Elevation mode and height input. Use Preview Profile to inspect the sampled profile. Grade Limit uses graph units; see Elevation and routing. |
| Water is missing from the preview | Water nodes return fields, not separate objects. Connect the intended height or surface field to Terrain Output and use the water mask in a color branch. See Drainage and Water. |
| Colors are missing | Connect a color output to Terrain Output's color input. Keep height connected too. A scalar mask cannot substitute for a color socket. In Heightfield Geometry, use Material Preview or the Terrain Color attribute. |
| Export does not start | Select the terrain that owns the graph. Set a valid destination, connect required inputs, then press the export button. If the file exists, choose a new path or enable Overwrite. Auto Update only updates previews. |
| Export reports a discarded result | Its source branch, source file or dimensions changed during evaluation. Finish editing and export again. |
| Export runs out of memory | Check graph complexity, connected maps and available RAM as well as VRAM. Try a smaller trial export. Grid Reduction reduces mesh density but not graph evaluation cost. See Native resolution and memory. |
| Exported terrain is rotated or has the wrong height | Import with Y Forward, Z Up and scale 1. Mesh export already includes Terrain Size and Height Scale; raw heightfield export does not. See Export and Blender Materials. |
| Exported color is too dark or washed out | Match export and import color spaces: sRGB base color as sRGB, Linear / Data masks as Non-Color. Terrain preview lighting is not baked into textures. |
| Mesh and texture features do not align | Export the same final branch at the same Resolution without changing dimensions or parameters between jobs. Use the exported UV map. Large Grid Reduction can also remove geometric features that remain visible in the texture. |
Slow editing¶
Start at Preview Resolution: 1K, then inspect detail at 2K or 4K. Change preview lighting without rebuilding the terrain. For several expensive edits, disable Auto Update and refresh once afterward.
Enable a suitable Node Cache (MB) under Preview Cache to reuse unchanged upstream work. Its budget is RAM, not VRAM, and it does not cover all memory used by Blender. Clear Preview Cache releases reusable results; the next edit may need to recalculate them. See Preview Cache.
After reopening a project¶
Allow the preview to finish updating, or click Refresh Terrain Preview when Auto Update is disabled. Keep imported Heightfield Source files and any exported images or meshes with the project.