Has a problem or error come up since you started creating your mod? This section will be your basic troubleshooting page for the editors. As more errors are found and corrected, the page will be updated with new tips and tricks to fix them up!

This particular section is for troubleshooting modifications and addons. If you are having problems with the core, uneditted game of SOMA, it is recommended you ask in the Technical Support section of the Frictional Games Forum, since your problem has probably been covered before in more depth there by a developer or another forum member.

If your map is not loading, and you have since editted scripts for the mod, chances are that there is an error in your script. Most of the time, you will be prompted by a window with information about where the potential error is located in your script. It should look similar to this:

To fix these particular errors, note down the location of the error. Here we can see the error is in base_map.hps, Row 14, Column 25. Therefore, there is a problem either on or before Row 14. Inspect the code and figure out if you can pinpoint the error. Feel free to post in the SOMA Development section of the forum if you're having issues figuring out your error.

When testing your mod, either on start or in game, you may get an error similar to the original poster of this forum thread.

This error comes up when your modification cannot locate a particular map (or .hpm) file. This error will likely be caused when loading or changing map. In the case of:

Loading a map from Start: There is likely a directory or naming error in your main_init.cfg. The lines you want to be looking for are within the StartMap group, specifically the File and Folder attributes. Check for any naming errors or directory problems. Personally, mine say: File=“base_map.hpm” Folder=“mods /<modfolder>/maps/”.

Changing from one map to next: In your script, check your map transition script to make sure there are no errors in spelling. Be sure to check your modification's resources.cfg as well, you may not have declared your maps folder as a resource.

Check your modification's resources.cfg file and add appropriate directories to your assets, sounds, music, etc. Furthermore, make sure any custom assets are included in your modification when you release it and test it.

The best way to address this problem is you to have others test your map on their computer and ask for the hpl.log file which is generated to suit your modification each time they finish playing. If you can read the log file, you can determine what errors have come up on the other person's computer.

This will generically be caused by one of two things:

1. The model cannot find all connected submeshes.
   This means that there is a model or .dae file missing. You will know this is the case if when you place down a model and it does not appear in the editor (see the image above), and upon clicking where it is placed, does not actually select the model. To fix this, you'll need to open the model in the HPL2 Model Editor and locate where the referenced models are located in The Dark Descent or in Machine For Pigs. Make sure you copy all of them over into your SOMA directory, and it would be a good idea to try and keep them as close to the original directory as possible.
2. The model has all of its components but not its material (or all of its textures).
   This means you do not have the material or the textures (or even just the diffuse texture) in a recognisable location for your entity or static object. An example that comes to mind is the towels in A Machine For Pigs, as they base their texture off a carpet material file. To check what material it uses, you can open up the model in the HPL2 Model Editor and press the [+] button next to the mesh. It should show you the name of the .dds textures. Most of the time, all the materials and .dds files will appear there, but you can get all of them.

This is a problem caused by the meshes of some Amnesia: A Machine For Pigs models. I do not know if these problems will persist in HPL3, but if it does, the simplest way is to delete the .msh and the .anm files if there are any included with that particular model. That will generate a new .msh file which HPL3 can recognise.

If your map uses .dae models from your mod directory that are not part of SOMA, try deleting all .msh files in your mod's directory, as these will be regenerated once the map is reloaded in the editor and might solve the issue

This is likely caused by a problem with one (or more) of your objects in the map having a quotation mark in one of the textboxes under the respective properties of the object. (For example, in entities > urban > special > 00_01_newspaper_article, which is a readable, in the readables text box, we may have a quotation mark in there.

To fix this, try following the instructions at this forum post. Essentially, it teaches you how to use the logs of an error in the Level Editor to fix your issues by yourself! I have not yet found any other particular errors other than using quotation marks, but if they come up, I'll post them here.

This is a problem with normal maps not being applied or incorrectly applied to the material of something which has been imported or added to SOMA.

It can be fixed by adjusting the method of saving your normal map when using Photoshop's nVidia .dds plugin.

Aaron: Make sure you apply a normal map to your material, I have provided a small blank normal map in textures>technical I believe called blank.nrm. This should fix the problem. […] Yeah make sure it is saved through 3dc, we use the nvidia dds plugin for Photoshop for this. It is a setting where you choose which compression you want to use. Right now your normal map is sRGB so it's not correct!

Aaron's quote about this solution can be found in this forum thread.

<No errors yet. Found one? Add it here!>

This error occurs because steam_appid.txt is not in SOMA's steam folder. To fix it, navigate to SOMA's Steam folder, which by default, is located here: C:\Program Files (x86)\Steam\steamapps\common\SOMA and simply create a text file with Notepad, named steam_appid.txt. Within this text file, simply write 282140 and save the text file. Therefore, you should have something like this:

This is not required if you are loading your modifications from the mods folder and are not using Steam to publish your work on the Steam Workshop.

Official post from Frictional Games concerning this issue.

There are two kinds of Mod Pictures - one which you can see when you are viewing your modification in the ModLauncher, and the other which you can see when you are asked to select one for Steam to use. Since the Steam image has appropriate validation checks, this will cover the Mod Picture in the ModLauncher. As such, your picture may look like either of these two examples.

To fix this, you need to specify a “LauncherPic” variable to your entry.hpc file. You can learn about this by visiting this wiki page and viewing the Setting up a StandAlone entry. Make sure that your image is also a .png file (.jpg files are not supported) and it is named correctly. If you need help assigning it, the previously linked wiki page has an example set up you can download. If all goes well, it should display an image you want. In my case, I was able to fix it:

<No errors yet. Found one? Add it here!>

<No errors yet. Found one? Add it here!>

<No errors yet. Found one? Add it here!>

See Mod Launcher - Steam API failed to initialize! above for information on how to fix.

In general, 3rd Party Applications are not handled by Frictional Games troubleshooting if it is an error on the 3rd Party Application's part. However, there are times where some of the setting up of applications may require some additional assistance.

You are using an outdated version of CodeLite. Download the latest version and follow the new steps as found in CodeLite or CodeLite: With Pictures. (Forum Thread)

Make sure your installation of CodeLite is located on the same drive as what SOMA is. ( Forum Thread )

If you have a bug to report about the Level Editor post it in our dedicated forum post.

If you have a bug about the other editors, please make a post in the User Content Technical Support subforum. Describe to us how to replicate the problem and attach the appropriate log file, located at

C:/Users/<user>/Documents/HPL3/

If you have a bug about SOMA, in terms of modding or the core game, please post it in the Technical Support subforum and:

• Describe the problem in detail. How can it be replicated?
• What Operating System are you running?
• Attach your hpl.log file after the bug has occurred. You can find it by following Problem X of the Troubleshooting Guide, it is pinned to the top of the subforum.