Troubleshooting Guide
Common issues and solutions when working with HoloScript v3.3.0.
Installation Issues
npm install -g @holoscript/cli fails
- Permissions Error (EACCES): Use
sudoon Linux/macOS or run PowerShell/CMD as Administrator on Windows. Alternatively, use a version manager likenvmto avoid permission issues. - Node Version: Ensure you are using Node.js 18 or higher (
node -v).
Preview & Dev Server
Preview window is blank
- WebGPU Support: Some browsers require flags to be enabled for WebGPU. Try using Chrome or Edge and check
chrome://flags/#enable-unsafe-webgpu. - Large Assets: If your scene has many high-poly models, it may take a few seconds to load. Check the browser console (F12) for network errors.
"holoscript dev" doesn't reload
- File Watchers: If you have many files, your OS might hit its limit for file watchers. On Linux, increase
fs.inotify.max_user_watches.
Compilation Errors
VRChat: "UdonSharp not found"
- Ensure your VRChat Creator Companion (VCC) is updated and your Unity project has the UdonSharp package installed.
- Check that the
compile --target vrchatcommand is run from the root of your Unity project or that you've specified the output path correctly.
Unreal: "Unreal Engine source not detected"
- HoloScript requires UE 5.1+ for native C++ generation. Ensure your
UE_ROOTenvironment variable is set or the project directory is valid.
Syntax & Traits
"@grabbable" doesn't work
- Collision: Objects must have a collider to be grabbable. Ensure you have the
@physicstrait or a defined geometry shape. - Parenting: If an object is nested within another grabbable object, the parent might be capturing the interaction.
"composition" vs "object"
- Remember that
compositionis for top-level modules and scenes, whileobjectis for entities inside a composition. Nested compositions are allowed but should be used for modularity.