Overview[]
The starsector.log file is a text document generated by Starsector while it is running.
Typical log entries
It contains information regarding the background actions the game is taking, like file loading or campaign events. Mods can contribute to this by adding their own log entries to track actions or for easier debugging.
The file is of utmost importance when tracking down the root cause of a crash, as it contains a stack trace if an unexpected program shutdown was performed.
Read the log from the bottom up. For crashes start at the very bottom of the file and look up for the first ERROR. There may be many INFO lines from other threads between the bottom of the file and the erroring thread. Example
1915 [Thread-3] ERROR com.fs.starfarer.combat.CombatMain - java.lang.RuntimeException: Ship hull spec [derelict_mantlebore_body] not found!
java.lang.RuntimeException: Ship hull spec [derelict_mantlebore_body] not found!Note the thread that has the error. In the above example this is Thread-3. Scroll up from the error until you find INFO entries from the errorring thread. There may be many INFO lines from other threads between the error and that threads previous info. Example
1905 [Thread-3] INFO com.fs.starfarer.loading.LoadingUtils - Loading JSON from [DIRECTORY: C:\Games\Starsector\starsector-core\..\mods\Domain Exo Militarium (data\variants\dem_mantlebore.variant)]From this we now know it's an issue with a ship hull spec reference and also which file it is specifically occurring in, which aids troubleshooting greatly.
Once the .log file exceeds 50 mb in size, it will be amended with a number and a new log file will be created. This can result in multiple starsector.log files being present in the game directory, each with a number at the end.
Where to find the starsector.log file[]
The .log file is always located under Starsector\starsector-core in your game directory:
The directory in which the log file is located
Depending on if you the setting "hide known file extensions" enabled or disabled, the file might have a different name:
 With file extensions visible |
  Without file extensions visible |
The file might just be called “starsector” if you have hidden known file extensions.
The files “starsector.log.1”, “starsector.log.2”, “starsector.log.3” might not be present and are of no immediate use for problem solving.
How to properly post a log entry to Discord[]
Phones have problems displaying the log file if it is just uploaded as a file attachment, so it is usually preferred if the stack trace text is posted instead of the file.
To do this, just open the “starsector.log” file in any text editor (usually notepad).
If you have not restarted the game since the crash, the process is very simple – just scroll down to the end, copy the last few lines:
A typical stack trace
and paste them into the Discord chat.
If you are feeling fancy, adding ``` before and after the text like this:
will display it in an easily readable fashion and increase the chance for the problem to be solved:
Reporting a crash[]
As the important part for debugging is generated once the game crashes, the best moment to report a crash is immediately afterwards, before starting the game again.
Game start-up will generate a large amount of log entries and might move the crash relevant parts into the next file, if the 50 mb limit is exceeded – making it hard to find.
If you have restarted the game since the crash occurred, you can:
- Replicate the crash, then post the log without restarting.
- Try to find the stack trace in starsector.log, but it will no longer be at the end – instead, it might be somewhere in the middle, or might even have been moved to starsector.log.1 as new entries were generated and the file exceeded the limit.
You can search the file for “ERROR”, and might be able to locate it that way, entries that say “ERROR” but do not have a stack trace can be ignored.
Return to: Modding