Skip to content

Troubleshooting & Gotchas

When an asset fails to appear, a trajectory throws a SPICE error, or OpenSpace crashes on startup, check logs/log.html first and match the symptom against the known failure modes below.

Diagnostic Workflow

  1. Open <OpenSpace_Root>/logs/log.html in your browser (refresh after each OpenSpace run).
  2. Filter or search (Ctrl+F) for Error or Warning entries—OpenSpace logs exact Lua line numbers, missing file paths, and SPICE exception codes here.
  3. Open Settings Property Visibility Developer in the UI to inspect hidden node state flags (Enabled, bounding sphere radius, and active tile counts).

Screenshot Placeholder: log-html-diagnostics.png

  • Crop: Capture a browser view of logs/log.html showing color-coded Info, Warning, and Error rows with a Lua or SPICE error message highlighted.
  • Callouts: (1) Log severity level filter, (2) Source module (Lua, SpiceManager, GlobeBrowsing), (3) Exact file path and line number where loading failed.

Path, File & Archive Gotchas

Symptom / Error Root Cause Fix
Syntax error or invalid escape sequence in .asset / openspace.cfg Windows backslashes (C:\OpenSpace\...) inside Lua strings act as escape characters. Replace all backslashes with forward slashes (C:/OpenSpace/...) or use asset.localResource(...).
Asset works on dev PC, fails on show PC Hardcoded absolute drive letters (D:/...) instead of relative resource helpers. Use asset.localResource("file.ext") for files stored alongside the .asset inside ${USER}/data/assets/.
HttpSynchronization or UrlSynchronization fails to locate extracted files Downloaded .zip archive contains a nested root subfolder (e.g., archive.zip/folder/data.bin) instead of flat files. Flatten the zip structure or adjust your localResource path to include the nested subfolder name.
Custom .asset doesn't appear in Profile Editor File lacks the .asset extension (e.g., saved as my_asset.asset.lua or .txt) or sits outside ${USER}/data/assets/. Verify the exact .asset extension and confirm USER_ASSETS points to ${USER}/data/assets in openspace.cfg.

Network & API Rate-Limit Gotchas

Symptom / Error Root Cause Fix
Celestrak TLE/OMM downloads return HTTP 403 / timeout Celestrak enforces automated 24-hour IP bans when identical TLE endpoints are requested repeatedly during restarts. Point GPTranslation to a cached local .tle file while iterating on your asset, and only enable live sync for production.
WMS / WMTS planetary map tiles stay blank URL projection mismatch (server only serves EPSG:3857 Web Mercator instead of EPSG:4326), or blocked HTTPS/SSL certificate. Check log.html for GDAL HTTP errors and verify the WMS endpoint supports SRS=EPSG:4326 (or wrap in a <GDAL_WMS> XML file).

SPICE & Scene Graph Gotchas

Symptom / Error Root Cause Fix
SPICE(SPKINSUFFDATA) Current simulation date falls outside the .bsp kernel's start/stop time bounds, or a parent body kernel isn't loaded. Run brief.exe -c -t <file>.bsp naif0012.tls to inspect exact UTC coverage dates and set your profile's start time inside that range.
Unknown parent identifier on startup Node specifies Parent = "Mars" (or another body) before that planet's .asset has initialized. Add asset.require("scene/solarsystem/planets/mars/mars") at the top of your .asset file.
3D model (RenderableModel) is completely black No LightSources block was defined on the renderable, or face normals are inverted. Add a SceneGraphLightSource referencing "Sun" (or "Camera") and test with EnableFaceCulling = false.
Custom keybinding triggers an infinite freeze Keybinding calls a Lua action that programmatically triggers that same keybinding again. Remove self-referential key calls; bind keys directly to target setPropertyValue or navigation functions.