Troubleshooting

Everything on this page is a failure the app can actually produce, matched to the message you see on screen. Symptoms are phrased the way you would say them. Under each one is the cause and what to do about it.

Read the error first#

Dayside surfaces failures in four places, and each one carries the engine's own message plus a fix line. Check them in this order.

The status strip sits above every screen. It shows engine-offline errors, one-line degradation notices from the last render, and a reconnect hint. Each row has a dismiss X, so an error you dismissed is gone until it recurs.

The canvas overlay in the section editor owns the render's own state: ACQUIRING, QUEUED, PREVIEW STALE, a PASS FAILED pill with a retry action, NO ACQUISITION YET, or NO COLOUR RENDER YET.

The Job Dock, bottom-left of the globe workspace, keeps one card per long job including failed ones, so closing a modal can never read as success. A failed card shows the reason and a Try this: line.

The Acquisitions drawer holds every export. A failed or incomplete acquisition shows FILES MISSING or its raw status, plus the error line and the output path.

A finished render that carries warnings is not a failure. It means the engine degraded a step and told you which one. Those are covered under Renders that finish but look wrong. For what each control is supposed to do, see Rendering the satellite image.

Renders and acquisitions#

Acquire does nothing and a banner mentions the storage budget#

The render never starts. The engine refuses admission before any work begins, with the message render state storage budget would be exceeded and a fix line about freeing state storage or raising the budget.

Cause. The render queue keeps durable job state on disk: input snapshots, published frames, thumbnails. That store has a hard byte budget, 20 GiB by default (LORESAT_RENDER_STATE_BUDGET_BYTES). Admission checks used + estimated request against the budget and also checks that the free disk space covers the request. Free disk is usually not the problem; the budget is.

Before refusing, the queue asks its garbage collector to trim the oldest unpinned terminal jobs until the request fits. So a store that has simply accumulated old renders heals itself at the moment you click Acquire.

The refusal only survives that when pinned state alone fills the budget. Each registered world pins its last render and its current and previous thumbnails, and those are never pruned. A library of many worlds therefore has a floor the collector cannot go below.

Fix. Delete worlds you no longer need from the picker, using Delete files from disk… on app-managed worlds so the bytes actually go. Removing a world from the list only unpins its state if the world record goes with it. Finished export folders are never touched by any of this: they live where you chose and are yours.

The progress bar sits at 0% and never moves#

Two distinct messages appear here, both with a Re-render path.

The engine is no longer tracking this acquisition. Re-render to try again. means the engine restarted and its in-memory job did not survive, so no poll can ever resolve. The editor drops back to PREVIEW STALE if it still has a frame, or NO ACQUISITION YET if it does not.

The engine is not acquiring this section. Re-render to try again. means the render started server-side but the editor never bound to it, usually because you switched section mid-request. The job runs to completion on the server and the editor stops waiting on a binding it never made.

Fix. Click Acquire or Re-render again. Neither state needs a restart.

A render says QUEUED and nothing runs#

One render runs at a time. Global concurrency and per-world concurrency both default to 1 (LORESAT_RENDER_GLOBAL_CONCURRENCY, LORESAT_RENDER_PER_WORLD_CONCURRENCY), so a second request waits behind the first. The overlay shows QUEUED, POSITION n and the priority lane.

A world also holds a mutation lock while a job that writes to it runs. A render queued behind a Generate, a Deterrace or a coastline apply will not start until that finishes, and the scheduler moves on to a different world in the meantime rather than blocking.

Fix. Wait, or click Prioritise to move the job up one lane. Priority moves one adjacent lane per request (background to normal to high), so a background job takes two presses to reach high.

Acquire is refused with a queue-full message#

global render queue is full or world render queue is full. The queue caps at 200 jobs globally and 50 per world, counting anything not yet terminal. The fix line reads: Wait for queued work to finish or cancel an older request, then retry.

Fix. Cancel queued work from the canvas overlay or the Acquisitions drawer.

A second action is refused while one is running#

The engine allows one active job per world per kind, and refuses the rest with a 409 naming the job that holds the slot: render <id> is already active for this world, export <id> is already active for this world, generation <id> is already active for this world, or world mutation '<kind>' is active.

Fix. Wait for it, or cancel it. This is not a bug and there is no override.

I cancelled a job. Did I lose the work?#

No. Cancellation is cooperative: the flag is checked between passes, between export layers and at every stage boundary, and a cancelled job keeps everything it had already completed. A cancelled render keeps the preview steps it published. A cancelled export keeps the layers it already wrote.

A cancel confirmation only appears when a job is past 90%, because it may well finish before the cancel is accepted.

Renders that finish but look wrong#

The render pipeline degrades rather than failing. Every degradation is written into the render's warnings and shown as a notice row. If a section looks unlike the satellite style, read that notice.

The image came out as a flat elevation ramp#

Two warnings produce this, and both say rendering hypsometric instead.

The first is missing pixel geometry. The satellite style needs a recorded ground scale for the section, because every spatial parameter in it is in kilometres. Without it the style cannot run at all.

The second names scipy. The satellite style needs it for the multi-scale filtering that builds the texture base.

Fix. For the geometry case, the section has no physical scale recorded, so nothing in the Controls panel will help. Re-import or re-create the section with its map width and planet radius set. For scipy, the packaged app ships it, so seeing this means the installation is damaged; use your package manager's Verify or Repair action.

The rivers disappeared#

The warning names the numba flow kernels failing to import, or flow routing failing, and says the render fell back to the wetness proxy. Routed rivers are an enhancement on top of that proxy, so every routing failure degrades to a picture rather than an error.

With no routing there are no lakes either, because lakes ride the same flow. Several controls also go inert: ecotone_widen (Flow widening), lith_flow, base_flow and riparian_green (Green banks) all read the routed flow and do nothing without it.

Fix. A packaged install ships the kernels, so an import failure means a damaged installation. Note that the whole-world globe pass routes no flow by design, so a globe never has rivers or lakes; that is not this failure.

Sliders in Rivers or Lakes are greyed out#

Everything under Lakes and Water colour is disabled while the Rivers toggle is off, and Dryness and Min size are additionally disabled while Lakes is off. This is correct: those parameters are read only by the routing layer.

Transition width does nothing on a small map#

The Transition width slider (koppen_blur_km) is silently capped at about 10% of the section's extent. The panel shows an amber CAPPED AT <n> KM ON THIS MAP note under the slider when your value exceeds the server's computed cap.

A focus-area crop can also get a wider blend than you asked for. The engine raises the blur to at least 1.5 cells of the authored climate source's own pitch, which is what melts the nearest-neighbour staircase a crop inherits from a coarse world raster.

The beach ring vanished on a large section#

Every kilometre-denominated parameter converts at the working pixel pitch and floors at 1 pixel. Beach width defaults to 1.0 km, which is about half a pixel on a 1,000 km section at a 512-wide analysis grid, so it fades out. This is expected, not a scaling bug.

Relief shading looks blown out#

Relief and Relief shading are not interchangeable. Setting Relief (hillshade_exag) to its minimum does not remove shading: zero exaggeration collapses the gradient so every land pixel is multiplied by roughly 1.08 and then clipped, which blows snow, ice, sand and pale sediment out to flat white. That is an over-exposed image.

Fix. To remove the shading, set Relief shading (hillshade_strength) to 0%. That skips the hillshade pass entirely and is also a real memory saving on large renders.

Rendering and export are blocked#

Biome palettes unavailable, and everything is blocked#

The panel shows Biome palettes unavailable, the server's message, and the line Rendering and export are blocked to protect the saved look. with a Reload world button.

Cause. Palette preferences resolve against an immutable, hash-pinned catalogue of the packaged gradient strips. If the catalogue fails to verify, the engine refuses to render rather than substituting different palettes under your saved selection. Project-level satmaps overrides deliberately do not participate in that catalogue.

Fix. Click Reload world. If it persists, the packaged assets are damaged; use Verify or Repair.

An export refuses the water mask or the albedo layer#

The message says the layer needs the satellite style and that this section degraded to a non-satellite render, and points you at the section's pixel geometry.

Cause. water_mask and satellite_albedo are filled from the satellite composite's own traversal. If the render degraded to hypsometric, there is no composite to read, and the engine refuses rather than shipping a guess under that filename.

Fix. Resolve the degradation first, or untick that layer.

River mask, Snow mask or Normal map will not tick#

Those three are not built yet. They show a soon chip in both export dialogs and the API refuses them with an actionable message. water_mask is the shipped superset of river_mask, covering rivers, lakes and sea in one 8-bit grey image.

The biome mask rows are unavailable#

Both biome_mask and biome_class_masks are re-emissions of the authored Köppen crop, so they share one prerequisite. A world with no biome layer cannot produce either. Create one from the Biome brush panel, or drop those layers.

Terrain generation#

Generate is disabled or the dialog says the model is missing#

The Generate terrain dialog carries one capability message with an action. The wording tells you which component is at fault.

The first seven all resolve to the same action: repair or reinstall. The retail fix line reads Repair or reinstall Dayside to restore the packaged model or …the packaged runtime. The last one is a hardware problem, not a damaged install, and the message says so on purpose so the repair goes to the right place.

Terrain generation is optional. Import, painting, colour and export all work without any of it.

No supported GPU was found#

The onboarding capability chip reads Some components need attention and the GPU record says No supported GPU was found. The generate dialog's footer reports that there is no validated generation backend and that import remains available.

Cause. Terrain generation runs on NVIDIA CUDA. The engine treats the backend as ready only when an NVIDIA adapter is detected, PyTorch loads, torch.cuda.is_available() returns true, and the adapter reports a driver version. Anything short of that is refused rather than silently falling back.

Related messages and what each one narrows the problem to:

• No NVIDIA adapter was detected; import remains available. The machine has no NVIDIA GPU.
• PyTorch loaded but CUDA is unavailable. Usually a driver that is too old or a GPU already fully committed elsewhere.
• The backend runtime is installed but could not be loaded. The runtime is present but its import failed.
• The backend runtime check timed out. Try again. The probe did not return within 8 seconds. Transient. Retry.
• This GPU has no verified terrain backend in this release. An adapter was found but this release has not validated a backend for it.
• DirectML generation is Windows-only. / ONNX Runtime does not expose DirectML on this machine. / DirectML execution is not implemented in this build. DirectML is reported for diagnostics and is not a shipping path.
• CPU generation is diagnostic only. The CPU backend exists but is never selected for real work.

Fix. Update the NVIDIA driver, then click Check again in the setup wizard, or reopen the generate dialog. Nothing in the app can substitute a GPU.

Checking this PC takes minutes#

On a packaged install with the terrain runtime staged, the capability check fully hashes and leases the runtime component on every call. That component is several gigabytes across tens of thousands of files, and the check is CPU-bound in the verifier rather than disk-bound.

Cause. The closed-tree contract requires every file to be inventoried and verified, and nothing caches the result between calls.

Fix. Wait it out. It resolves rather than failing, and the wizard's chip settles once it does.

Generate fails with the terrain state folder missing#

The message reads the terrain state folder is missing and asks you to restart and retry.

Cause. The terrain state folder is classified as a cache, so Remove my data deletes it along with temp. It sits under the state root at terrain-runtime.

Fix. Restart the app. The server recreates the folder at startup with the protected permissions the runtime requires. Creating it by hand does not work: a folder made with inherited permissions is refused.

The terrain runtime could not start with the verified binding#

The generate job fails with exactly that sentence.

Cause. The runtime process never spawned. The commonest reason is the missing state folder above.

Fix. Restart the app and retry. If it recurs, the reason is printed into server.log with a [loresat] prefix, and that line names the actual cause including the child's exit code.

The diffusion server did not start within 180s#

A queued generation must be claimed within 180 seconds or the engine concludes the server never came up, and fails the job with that message pointing at the sidecar log.

Fix. Read the sidecar server.log (see Where the logs live) and retry.

Generation sits at 85% for a long time#

Not a failure. The terrain model reports only elapsed time while it runs, so the progress bar has nothing real to show. Once generation starts, progress creeps asymptotically toward a hard ceiling of 85% with a 45-second time constant, then jumps when the pass finishes and finalising begins.

The chunked path a large section auto-routes to behaves differently: it reports a true fraction, one step per completed chunk, because chunks land on disk as they finish.

Terrain came back at the wrong feature scale#

The model you pick sets the physical size of a coarse cell, and that is the scale contract for the whole pass. The 30 m model uses 7.7 km cells (playable scale). The 90 m model uses 23.0 km cells (continental). Base-lite runs its own fixed recipe at 23.6 km cells and about 1.18 km/px.

Pick the wrong one and you get plausible-looking terrain at the wrong scale, with no error anywhere.

Fix. Match the model to the section extent. The dialog prints a guidance line when you are outside the sensible band, for example when a 30 m run spans more coarse cells than the 128-cell continental threshold. Enhancing terrain covers the choice in full.

The sea level crept up after a second Generate#

It should not, and if it does the cause is worth knowing. Conditioning is rebuilt from the authored land heightmap and bathymetry on every run and is never read back from a previous generation's signed output. A second Generate is another pass over your authored terrain. Without that rule each fresh run would condition on the last drifted result and the datum would ratchet.

What does move the datum is changing Sea level in the Controls panel after a generate. The panel says so: changing it then reclassifies model-authored land and ocean. Set it before you generate.

Fix. Use Revert to authored heightmap in the generate dialog, which is available whenever a pre-generation snapshot exists.

Worlds, loading and the engine#

A world sits on Loading project and never opens#

Almost always this is waiting for you. Clicking a world card raises the loading modal, which warms the layers and then gates entry behind an explicit Open <name> button. The caption changes to Layers restored and preview warmed when it is ready. There is a minimum on-screen time of two seconds, so a fast open still shows the sequence.

A world imported in inferred mode goes to the flat-or-world fork instead, which needs Open editor or Open world.

If the modal genuinely failed it says Could not warm this project and offers Try again.

Couldn't open this world#

The picker raises a dialog with the server's message, an optional fix line, and Dismiss / Retry.

Cause. The world's defaults could not be fetched, so the editor has nothing to open with. Away from the picker the same failure appears in the status strip as Could not open <name>: <message>.

Can't reach the Dayside engine#

With no worlds on screen you get the full takeover: the chip ENGINE OFFLINE, the heading Can't reach the Dayside engine, the line The local backend isn't responding., a Retry connection button and a LAST ATTEMPT detail line. With worlds already on screen the same failure appears as a dismissible status-strip row.

The picker retries by itself every 5 seconds while it is offline, so a backend that comes back is picked up without you doing anything. Your worlds are on disk and are not at risk from this.

Reconnecting to the engine#

A quiet strip row, shown only when the event socket has been down for more than one retry cycle and a world is open. The engine is alive; the live event feed is not. Jobs continue server-side and each job also has a polling fallback, so progress catches up when the socket returns. Job Dock cards show reconnecting… while this is happening.

Every world is gone from the picker#

Check the search box first: an empty result reads NO WORLDS MATCH "<query>", which is a different state from the empty takeover (NO WORLDS YET).

Removing a world from the list never deletes files. For an app-managed world the folder stays on disk until you take the second, separately worded Delete files permanently step. For a project you opened in place, removal only takes it out of the list and the folder is untouched.

The globe#

Globe out of date#

The status chip on the globe canvas reads Globe out of date in amber, with a banner summarising what changed, for example 3 regions changed · 1 tile edited.

This is a fact, not a fault. Region and tile work does not fold itself back into the sphere. Re-compose globe is the non-destructive pass that folds everything you edited into a fresh mosaic.

Colour globe refuses to run because tiles have edits#

The job fails with a count and the sentence that re-colouring the globe would discard those edits, and the fix line offers two routes.

Cause. Colouring the globe from scratch deletes every globe-colour tile on disk first. If you have edited any tile since the active mosaic was published, that work would go silently.

Fix. Either run Re-compose globe, which folds the edits into a new mosaic, or tick Rebuild all tiles, discarding N per-tile edits in the Enhance world dialog to rebuild everything from scratch on purpose.

Export globe's resolution buttons are all disabled#

Every numeric resolution is disabled until the globe has retained tiles, with a note telling you to run Re-compose globe first.

Cause. The on-globe display composite is capped at 4096 px on its long side. A high-resolution export re-composes from the retained per-tile crops, which hold the full detail, up to 32K. With no retained tiles there is nothing to compose from and only Native · as displayed can ship.

Colour globe or Re-compose fails saying there are no tiles#

colour the globe before re-composing (no globe-colour tiles found) or the equivalent for updating. Both passes read the active mosaic's tile records. A world that has never been coloured has none.

Fix. Run Colour globe from the Enhance world dialog first.

A region will not draw#

Region creation validates the selection against the oblique Hammer projection and refuses anything it cannot represent as one low-distortion crop. The messages are specific:

A region that overlaps an existing one is refused only when you set Overlap policy to Reject overlap. The dialog then offers an inline Allow overlap button so you do not have to redraw.

The globe view turned into a flat map#

The stage falls back to the flat selection surface when its pane is under 280 px on either side. Widen the window or collapse the side panel.

If the GPU drops the WebGL context, the globe releases its capture and rebuilds when the context is restored. You may see the view reset. Nothing is lost.

A tile shows the wrong size#

Two extents exist for every crop and they are not the same number. The size on a region card is the selection's own great-circle span, before the feather margin. The persisted raster is larger, because it includes that margin. They diverge by twice the margin, which is around 20% on a focus area with the default 32 px feather and around 45% on a globe-colour tile.

Imports and sea level#

My imported map came out all land, or all sea#

The waterline is authored at import time and nothing recovers it afterwards without a re-import.

Cause. The Waterline slider on the Sea & terrain step decides which brightness counts as sea level, defaulting to whatever the server proposed from the heightmap's own histogram. The step tells you what you are choosing: About N% is below the proposed waterline. A heightmap that does not use black for the seabed will propose badly.

Fix. Read the waterline off a reference instead of guessing. The same step has Set sea level from a land mask and, when you supplied one with ocean in it, Use my climate map's ocean. The reference must be the same pixel size as the heightmap. If you already built the world, re-import. Setting up a world walks the whole step.

The sea is flat and the coastline reads as a cut edge#

Cause. The Deep-ocean floor choice on the import step. If your heightmap has no real bathymetry and you told the app it does, everything below the waterline is flat, which reads to the terrain model as flat land rather than a coastline.

Fix. Use No depth in my maps with Synthetic sea floor on, which builds a shelf, a slope and an abyss. Or attach a real bathymetry image with land in pure white under Separate depth map.

Note that setting Use bathymetry off in the generate dialog does not mean land-only or ocean-at-zero. It keeps a constant ocean floor at the depth you set, because the model was trained on real elevation data where the sea floor is negative metres, and ocean-at-zero makes it invent coastal relief.

Rivers and climate came out wrong after attaching a rainfall map#

Cause. The Rainfall at white (mm/year) number is the only record of what your map's brightness means in millimetres. Get it wrong and nothing visibly breaks. Terrain generation substitutes its own 3,000 mm/yr default and conditions the model at the wrong scale, producing a plausible world with the wrong climate.

The staged confirm panel warns you about two specific shapes:

uniform means the map is a single flat value with no variation at all, so it will not make rivers or terrain any more climate-aware than having no map. Check you exported the rainfall channel rather than a blank layer.

saturated means a share of the map sits at pure white and was probably clipped, so the real peak is higher than the number you entered.

Fix. Set the number to your source's actual maximum, or re-export without clipping. The panel re-analyses as you change it and shows the driest, mean and wettest values it resolves.

A world with no climate map renders as rainforest#

Cause. With no authored Köppen layer the engine classifies climate from temperature and altitude alone, and that classifier cannot place arid or Mediterranean climates at all. Anything at or above 18 °C reads as tropical, which carries 2,000 mm/yr of precipitation. That is very wet for the snow and lake models, so snowlines sit low and basins fill.

Fix. Author a climate layer. Upload a Köppen-coloured climate map at setup, or paint one with the Biome brush.

The climate map was rejected#

Climate maps must be lossless 8-bit PNG and the same pixel size as the heightmap. Rainfall maps and bathymetry maps carry the same size requirement. The upload errors name the dimension mismatch directly.

A round-tripped Gaea heightmap came back at the wrong height#

Cause. The Gaea Height you exported with field. The import writes the heights the file carries, so the number has to match what you set in Gaea. On a section wider than Gaea's map cap the export sheet pre-scaled the Height to keep the height-to-width ratio, and the dialog shows that factor.

Fix. Use the _heightmap.json sidecar written beside the exported file. Add sidecar… takes its numbers instead of the ones you typed. Or tick Match the previous peak to keep the shape you sculpted while restoring the height the section had. Revert restores the heightmap from before the import.

Painting#

Apply coastline refuses because paint is not applied#

Your painted changes aren't applied yet. on the Landmass or Coast panel.

Cause. Both tools preview from the applied terrain, so running one would discard unapplied strokes.

Fix. Click Apply changes first.

The coastline preview will not update#

The canvas badge tells you the preview failed and to adjust the settings. The panel shows the server's own message, falling back to The preview could not be computed.

Fix. Change the settings and let it re-preview. Nothing has been written to the heightmap, and Cancel discards the pending batch.

Edits at a working resolution have not reached the master#

The edit-proxy banner reads Editing at 4K · native 8,192×8,192 · N edits not yet baked.

The bake is never automatic. Your full-resolution master stays untouched until you click Bake to native, which replays your edits onto it. Discard throws the proxy edits away and restores the master.

Where the logs live#

Nothing here is uploaded anywhere. All of it stays on your machine, and you attach it yourself if you file a bug.

The support bundle is the thing to send. Open About & credits, expand Diagnostics, and click Preview what a bundle contains first: it lists exactly what goes in and what never does. It contains release and policy digests, component reason codes, GPU and driver labels, and redacted tails of the shell and server logs. It excludes your worlds, model bytes, tokens, absolute paths and environment variables. It is capped at 256 KiB, and paths and tokens inside the log tails are redacted before they are written. Tick the consent box and click Create bundle and save to this PC.

Raw logs, if you want the untruncated version:

%LOCALAPPDATA%\Loresat\v1\logs\shell.log     the desktop shell
%LOCALAPPDATA%\Loresat\v1\logs\server.log    the engine

server.log is where the engine's own reason lines land, including the [loresat] lines that explain a runtime that refused to start.

Job state on disk. The render queue keeps a durable record per job. Each one has a status.json, and its input snapshot and published frames sit alongside it:

%LOCALAPPDATA%\Loresat\v1\render-queue\v1\jobs\<job id>\status.json
%LOCALAPPDATA%\Loresat\v1\render-queue\v1\artifacts\
%LOCALAPPDATA%\Loresat\v1\render-queue\v1\thumbnails\
%LOCALAPPDATA%\Loresat\v1\render-queue\v1\quarantine\

Terrain sidecar logs live with the sidecar, not with the engine. A generate failure that names server.log means that one. A whole-world terrain pass writes tool.log into its own job folder, and its failure message names it.

App-managed worlds live under the state root in synthetic_worlds, imported_worlds and uploaded_worlds. A project you opened in place stays wherever you put it and is never written to outside its own folder.

Exports default to <world folder>\loresat_exports\<time>_<section>_<destination> and are never pruned by anything the engine does. Every finished acquisition in the drawer shows its full path with a Copy path button.