Troubleshooting

← Home

• Common errors
• Performance tips
• Diagnostic tools
• Config reset
• Reporting bugs

Common errors

CLI input validation

Message	What it means	Fix
Model file does not exist: <path>	Path doesn't resolve	Use an absolute path; check spelling
Path is not a file: <path>	You passed a directory	Specify the model file itself
Invalid file extension '.<ext>', expected '.obj', '.stl', '.ply', '.gltf', or '.glb'	Format not supported	Convert or rename to a supported format
File has no extension, …	No extension to detect format	Add the appropriate extension
Error: --format json requires --mode analyze	-f json only works in analyze mode	Use -M analyze together with -f json
Model path is required for analyze mode (use -m <path>)	Analyze needs a model	Pass -m <path>

Runtime errors

Black or incorrect rendering - your GPU drivers are likely out of date. Solarxy needs Vulkan, Metal, or DirectX 12. Run solarxy --verbose and check the console (`) for backend selection messages.

Materials or textures missing

• OBJ: ensure the .mtl file lives next to the .obj and the texture paths inside the MTL resolve. Right-click → Copy in the in-app console will give you the exact path Solarxy tried.
• glTF: external texture files must be present relative to the .gltf. Prefer .glb (everything embedded) for portability.

For format details (UV requirements, embedded vs external textures, the auto-detected PLY companion texture), see User Guide → Supported file formats.

Warning: invalid msaa_sample_count <N> in config - only 1, 2, and 4 are valid. Solarxy falls back to 4 and continues. Fix the value via Edit → Preferences… → Startup.

Warning: failed to parse config.toml - invalid TOML syntax. Solarxy uses defaults when the file can't be parsed. Either fix the file (open it from Edit → Preferences… → Startup → Open config file) or reset it.

HDRI errors - the dropped .hdr / .exr couldn't be parsed. Verify the file is a valid HDR image (Solarxy uses the image crate; some unusual sub-formats aren't supported).

Unsupported format: .<ext> - drag-and-drop accepts model files (.obj, .stl, .ply, .gltf, .glb) and HDRI files (.hdr, .exr) only.

Esc closes a modal but doesn't quit the app - that's intentional since v0.5.0. Esc dismisses open modals (Preferences, Update, About, Keyboard Shortcuts, file dialogs). To quit, close the window or use File → Quit.

Review system

Markers don't appear after reopening a model - Solarxy compares the model's current SHA-256 to the hash recorded when the sidecar was last saved. A mismatch flips all anchors to the Needs re-anchor section of the panel (markers render dimmed in-viewport). Open the panel, expand "Needs re-anchor", click Re-place here, then click the corrected position on the model.

Sidecar not found - by default Solarxy looks for <model_stem>.solarxy-review.json next to the model file. If you've set [review].sidecar_dir in solarxy.toml, check that the override path is correct and that relative paths resolve against the model's parent directory (e.g. sidecar_dir = ".solarxy" puts the file at <model_dir>/.solarxy/<stem>.solarxy-review.json).

Annotations show as "anonymous" - attribution is opt-in. Set your display name in Edit → Preferences… → Interface → Reviewer name, or add [review].author = "Your Name" to your config.toml. See FAQ → Why are my annotations anonymous? for the design rationale.

solarxy.toml parse errors

The project config uses strict parsing - unknown fields hard-fail with a clear line + column reference and a "did you mean?" suggestion when there's a close match:

solarxy.toml:14:5: unknown field `flipped_normal_dott` (did you mean 'flipped_normal_dot'?)

If you see format_version = N (this build supports M). Reading on best-effort basis., the file was written by a newer Solarxy than what's installed. It still loads, but some sections may be ignored. Upgrade Solarxy or downgrade the config to match.

Dock layout wedged

If panels end up in unrecoverable positions, use Window → Reset Layout to Default. This rebuilds the default arrangement without touching either persisted blob ([dock].last_layout_json or [dock].saved_layout_json) - your saved snapshot survives, the live layout resets.

If a persisted layout fails to deserialize (e.g. after a Solarxy upgrade that added a tab variant), Solarxy silently falls back to the default and logs a tracing::debug! line. Set RUST_LOG=solarxy=debug to surface it:

RUST_LOG=solarxy=debug solarxy

Batch validation (CI)

The most common batch-validation issues are documented inline in the recipe references:

• --paths seems to do nothing / the GUI launches. You omitted --mode analyze. See CLI Reference → Batch validation.
• no model files matched. Quote your glob patterns so the shell doesn't pre-expand **; globs resolve relative to the current working directory.
• UnsupportedFormat error. The adapter / format combination is unsupported. See CI/CD Integration → Adapters and formats.

For the full CI-specific troubleshooting list, see CI/CD Integration → Troubleshooting.

Performance tips

If frame rate is poor or input feels laggy:

Approximate, GPU-bound. The relative cost ranking below holds across typical GPUs, but the absolute savings vary by hardware and asset complexity. Measure on your own setup before committing to a global change.

Approximate cost	Action	Where
High	Drop MSAA from 4× → 2× → 1×	Edit → Preferences… → Startup, MSAA selector. Takes effect on next launch.
High	Cycle IBL down to Diffuse or Off	Shift+I, or sidebar Lighting group
Medium	Disable bloom	Shift+D, or sidebar Post-Processing
Medium	Disable SSAO	Shift+O, or sidebar Post-Processing
Low	Drop wireframe weight to Light	Shift+W

Large models (millions of triangles) take longer to load; the viewer shows a loading toast during this time. After load, frame rate is GPU-bound - the bottom status bar shows live frame time and fps (toggle it from Window → Status Bar).

Diagnostic tools

In-app console (`) - toggles a tracing-backed log viewer. Filter by ERROR / WARN / INFO / DEBUG; substring search the message column; right-click any line to copy. Default capture is solarxy=trace and is not user-configurable in-app; set RUST_LOG=<directive> before launching to change the captured filter.

Verbose CLI logging:

solarxy --verbose -m model.obj
solarxy --log-level solarxy=debug,wgpu_hal=warn -m model.obj
RUST_LOG=solarxy=debug solarxy -m model.obj

Install source + version:

solarxy-cli --about

This prints the version, repository, and license - useful when reporting a bug.

Config reset

Preferences live in a TOML file at a platform-specific path. To reset everything to defaults, delete the file. Solarxy recreates it on next save.

OS	Path
macOS	~/Library/Application Support/solarxy/config.toml
Linux	~/.config/solarxy/config.toml
Windows	%APPDATA%\solarxy\config.toml (typically C:\Users\<User>\AppData\Roaming\solarxy\config.toml)

You can also open the config file from inside the app: Edit → Preferences… → Startup → Open config file.

To reset only one tab's worth of settings, open Edit → Preferences… and click Reset to defaults - it only mutates the active tab (Startup / Appearance / View / Interface / Updater).

Deleting the whole config.toml also resets the v0.6.0 [review] and [dock] sections. If the issue is just a wedged dock layout you can leave the rest of the file alone and edit out the two last_layout_json / saved_layout_json lines.

Reporting bugs

Open an issue with:

• OS + version
• GPU + driver version
• Solarxy version (solarxy-cli --about)
• Steps to reproduce
• Output from solarxy --verbose if relevant (or right-click → Copy from the in-app console)

See also: Installation · CLI Reference · Configuration · CI/CD Integration · User Guide