Skip to content

Troubleshooting

Jump to bottom
TeeCodeDev edited this page Sep 27, 2026 · 4 revisions

Troubleshooting & FAQ

Encountering an issue or unexpected behavior? Here are solutions to common questions and setup checks.

1. I don't see any models after starting the container

  • Volume Mappings: Verify that your /library Docker volume path accurately points to the directory containing your 3D files on the host machine.
  • Supported Formats: GyroidVault indexes .stl, .3mf, .step, .stp, .obj, .f3d, .gcode, .bgcode, and .zip archives.
  • Scan Status: On a fresh install, head to Settings → Maintenance and check if a background scan is running or click Scan for New Files.

2. Can GyroidVault handle very large libraries (2TB+ / 20,000+ models)?

Yes! GyroidVault v2.1+ and v2.2 are specifically engineered for huge repositories:

  • Paginate-Then-Hydrate Queries (v2.1.1): /api/models loads 20,000+ model libraries in under 80ms by hydrating file counts and metadata only for the active page.
  • Batched Hourly Disk Sync: Physical disk synchronization runs in non-blocking batches with an active re-entrancy guard, preventing unnecessary disk I/O and keeping NAS drives quiet.
  • 300MB Archive Guard: Compressed .zip archives larger than 300MB are cataloged without buffering their entire contents into RAM, avoiding Out-Of-Memory crashes.

3. I don't want GyroidVault to scan inside my .zip archives

  • Go to Settings → General and toggle off Scan & Index ZIP Archives.
  • The setting auto-saves immediately. When disabled, .zip files are treated as regular single files rather than deep-scanning the 3D models inside them.

4. The 3D viewer is slow or won't load

  • WebGL Hardware Acceleration: Ensure hardware acceleration is enabled in your browser settings (chrome://settings/system or edge://settings/system).
  • STEP File Tessellation: Large parametric .step / .stp CAD assemblies are tessellated in a background WebAssembly worker (occt-import-js) and may take a few seconds on first load.
  • High-Polygon Meshes: Extremely dense 3D scans (50M+ polygons or files >200MB) can saturate browser WebGL memory.

5. "Open in Slicer" doesn't launch my application

  • Make sure the slicer is installed on the computer you are browsing from (not the server!).
  • Check if your browser blocked protocol handlers. When prompted the first time, check "Always allow".
  • Bambu Studio Users: Ensure you are running GyroidVault v2.1.0 or newer, which automatically wraps raw .stl files into a .3mf package on the fly for ambustudio:// compatibility.

6. Mac / Apple Silicon Users (localhost not responding)

If GyroidVault doesn't respond on http://localhost:3457/ immediately after starting the container on macOS:

7. Where can I report bugs or ask questions?

Clone this wiki locally