Headless Server Software/Troubleshooting: Difference between revisions

Latest revision as of 00:45, 2 June 2024

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.

@@ Line 1: / Line 1: @@
 {{Stub}}
+When you're having trouble running a headless, you can follow this guide for some troubleshooting tips.
-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 [[Headless_Server_Software/Example_Configurations#Minimal|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 [[Log Files|Logs]] ==
@@ Line 20: / Line 22: @@
 # 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 [https://github.com/Yellow-Dog-Man/Locale/edit/main/en.json Locale files].
+# Take the text after the colon(:) in "Error logging in:" and search for it in our [https://github.com/Yellow-Dog-Man/Locale/blob/main/en.json Locale files].
 #* This will translate the error into a proper message for you that you can then follow for further instructions.
@@ Line 26: / Line 28: @@
 == Configuration Formatting ==
-It is always worth copying your [[Headless Server Software/Configuration Files|Configuration File]] into a [https://jsonlint.com/ JSON Linter] to check that it is a valid [https://www.json.org/json-en.html JSON] file.
+It is always worth copying your [[Headless Server Software/Configuration File|Configuration File]] into a [https://jsonlint.com/ JSON Linter] to check that it is a valid [https://www.json.org/json-en.html JSON] file.
-You can also paste your [[Headless Server Software/Configuration Files|Configuration File]] into the text box on the right of a [https://www.jsonschemavalidator.net/s/x55MvwdB JSON Schema Validator] to check it has no errors.
+You can also paste your [[Headless Server Software/Configuration File|Configuration File]] into the text box on the right of a [https://www.jsonschemavalidator.net/s/x55MvwdB JSON Schema Validator] to check it has no errors.
 You can also use [https://github.com/Yellow-Dog-Man/JSONSchemas/blob/main/schemas/HeadlessConfig.schema.json the schema itself] via other [https://json-schema.org/implementations 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 specific worlds from their world collection.
+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 <code>resrec:///</code> URL for the world.
+If you'd like additional assistance with world issues then follow the [[Headless Server Software/Loading a Specific World|guide for that]].
+== Where to go next? ==
+If you're still having trouble then you can ask in our [https://dicord.gg/resonite Discord] or post an issue on our [https://github.com/Yellow-Dog-Man/Resonite-Issues issue tracker].
 [[Category:Troubleshooting]]