Troubleshooting
Check out this page for solutions to common issues.
One of the most common issues when starting is that the playground files won't build. This is usually because the WebGL module was not installed when you installed Unity.
If you look at the console when trying to build the playground files, you will get an error similar to the following :
Example WebGL error
- Go to the Unity Hub Installs section, selecting the Settings button, and then go 'Add Module'.
- Make sure the WebGL module is selected and select 'Install' at the bottom.
Select the Add Module option
Installed WebGL Module
- Another approach, if you are not using Unity Hub, is go to 'File > Build Settings' and then switch the Platform to WebGL. This should install the WebGL module as well.
A lot of issues are caused by Scenes or tags being used incorrectly or not at all. Mona needs the following applied exactly like this in order to function correctly, so make sure to keep the following in mind.
Space Summary
The next image is a summary of the object types and the applicable states of each. Some of these are compulsory as well, so make sure these are set accordingly.
Other considerations to make in your hierarchy
You will need to add colliders to all objects you want the avatar to walk on, or not walk through. Box Colliders are most performant, but if you need a mesh collider make sure to optimise the mesh and use that instead of the base mesh. For more information go to Colliders.
This means that there is probably an object outside of the Space/Portals/Artifacts Scenes or parent gameobject hierarchy. If you collapse all your folders to the top gameobject layer you should get something like this :
Reduced hierarchy should look like this
If there are any other objects under the Space/Portals/Artifacts scene, then make sure to add them under the Space/Portals/Artifacts gameobject.
The first object under each scene is the 'layer' in which all your objects need to be under. The Tags (in green) should be as follows :
Object tag in hierarchy
Make sure that there is only one of each green tag in the space. Any duplicates will throw an error. Other tags (Portals/Artifacts/Canvases) use different tags.
Make sure that your space doesn't have a camera in the scene. Either delete or disable the camera before building your Space to Playground Files.
Make sure to delete your Playground Files after testing. Sometimes it will not overwrite the files when you build them.
First thing is to check the web console for errors :
- Edge > Settings in top right / More Tools / Developer Tools
- Chrome > Settings in top right / More Tools / Developer Tools
This is the best way to help figure out what may be happening. Common issues include :
If an error is 'Nullreference : Object Reference not set to an instance of an object' then there may be a broken connection between objects.
A common issue is that Artifacts, Portals or Canvases (the Unique name object with the respective tag) does not have a collider and it needs it.
It could be by deleting prefabs without unpacking/deleting the references in the scene, renaming or importing a object that is different in some way to what Unity is expecting, references to objects in Unity Animation, or a reactor reference perhaps.
Basically, something in your scene is looking for something else in you scene, and not finding it.
It could be that your internet connection times out before it can upload, resulting in the following error. Make sure that you have a fast enough internet connection to upload your space without issue. Sometimes this may just be a temporary issue, and may work in an hour or two.
Example issue
This error will happen when you have moved or renamed your space scene in the project file outside of the original location, breaking a lot of the internal references that Mona is looking for. Unity will not fix this if you rename it back in some cases.
Error in question
This can be fixed by copying the Space.unity.meta file from an alternative build (found in the Space location) and copying it to the same location once you have sent the Space file to it's original location.
An alternative approach is building the Mintable file of your space using the Mona Menu, and then importing that into a new Template. This process is shown Testing the Mintable File. You may need to copy any other assets across, but this should solve this problem.
Occasionally, the Unity Hub can be a little problematic for some uses. One thread that may help is the following, as it has links to earlier version of the Unity Hub.
Other approaches may be make sure that your VPN is turned off and that Unity is allowed through the firewall on your computer. These may limit your ability to sign in with the Personal license, and if you can't sign in you won't be able to open Unity.
You may have covered the Portal, Artifact, or Canvas collider with another collider (usually for physical collision on the assets themselves). If there is a collider in front of, or surrounding, the collider on the Unique###Name gameobject then that will get priority, meaning the asset will not be able to be seen in Mona. As the portal, artifact, or canvas collider is also a physical collider it's best to remove all other colliders on your assets.
Another reason is that you may have deleted the Collider on the gameobject that has the Unique###Name and Portal/Artifact/Canvas tag attached (as per the documentation).
The following error appears when loading the space :
Javascript error
A common reason for this is when the canvas images are to numerous, or too large, for the browser memory. Make sure your images are as small as possible if you have many images. we recommend no bigger than 1000x1000 if possible as all these images will need to be loaded before a user can explore the space without lag.
Another reason is that you are using too many animated GIF images. Reduce the number of gifs and see if that works. The filesize of the animated gifs may not be a deciding factor on this.
Canvases MUST have a mesh collider on the Unique Name Gameobject that has the Canvas tag (Not the CanvasPrefab parent object). If it has any other collider type, or no collider at all, it will throw an error on uploading to the playground files on your wallet.
This means that that two or more UniqueName gameobjects (with their respective tag) under different Portal/Artifact/Canvas Prefabs have the same name. Use the QA button to give you hints to which ones inside Unity.
This is a shader issue usually related to render pipelines. You may be using a shader on your material that the inbuilt render pipeline is not compatible with. URP and HDRP are not compatible with Mona.
If you are porting your assets from either URP or HDRP, played with these settings by mistake, or added an incompatible shader type from the asset store then you will need to reset the material or render pipeline to the Standard Render Pipeline.
This is most likely due to your space not having Lightprobes. For more information go to Light Probes.
It is recommended to close your mesh before export. Although the collision is based on the normal, or the polygon facing direction, of the mesh. Also make sure to apply all transforms before exporting.
Deleting the Mesh Collider component and reapplying it will sometimes fix this issue.
If the Spaces don't load on the website you can always check the 'Browser settings > More Tools > Developer Tools' window, make sure the 'Console' tab is selected, and see if that offers any errors to help troubleshoot. This helps troubleshoot the issue in the Support channel on Discord.
If the following error is shown it could be related to your Antivirus software.
Website spaces don't load...
This happens sometimes when your hard drive that unity uses for temp files is full. Check your main drive and make sure there is enough space.
Last modified 10d ago