This article or section is a Stub. You can help the Resonite Wiki by expanding it.
When you're having trouble running a headless, you can follow this guide for some troubleshooting tips.
Start Simple
If you're having issues and in particular if this is the first time you've used the Headless Server Software, then we recommend attempting to run the headless with a minimal configuration file. This file uses the bare minimum of properties to get you a running session on a headless. If this doesn't work, it is unlikely anything else you are trying will work.
Examing the Logs
Headless Server Software outputs the same logs as a regular Resonite client. So the first step should be to examine any relevant Log Files that might have been produced by the Headless.
When looking through them check for items like:
- Error Logging In
- Error
- Exception
etc.
If you find something and you need help understanding what to do, you can try continuing to read this article or you can post on our Discord.
Login Issues
The Headless Server Software currently doesn't support Locale strings for login errors. Due to this, it might be harder to locate a login error but here are some tips.
- Search the Log Files for "Error logging in:"
- If you find this then it means the reason your headless isn't working is due to a login issue.
- Take the text after the colon(:) in "Error logging in:" and search for it in our Locale files.
- This will translate the error into a proper message for you that you can then follow for further instructions.
If in doubt, you can also try logging into the headless account from a regular Resonite installation which will also indicate if your Resonite account is working.
Configuration Formatting
It is always worth copying your Configuration File into a JSON Linter to check that it is a valid JSON file.
You can also paste your Configuration File into the text box on the right of a JSON Schema Validator to check it has no errors.
You can also use the schema itself via other tools that are capable of reading them. We recommend Visual Studio, or Visual Studio Code which natively support JSON Schemas.
World Issues
A common goal for Headless users is to load a specific world.
When doing this, and experiencing issues check the following items:
- That the world is saved and up to date
- That the world is able to be opened by any user.
- You can also store a world in a Group folder and then provided the Headless user is in that Group it should load.
- That you have a valid
resrec:///URL for the world.
If you'd like additional assistance with world issues then follow the guide for that.
Where to go next?
If you're still having trouble then you can ask in our Discord or post an issue on our issue tracker.