diff --git a/development.rst b/development.rst
index 4d029e42a767aa17d4ddc14a3bf76d3cd3f9d8d9..f034c980cf4e54eb7b229063b89c4b24950fae5b 100644
--- a/development.rst
+++ b/development.rst
@@ -17,3 +17,20 @@ Then every time you commit, pre-commit will run all checks defined in `.pre-comm
 you can run the pre-commit checks manually by running::
 
     pre-commit run --all-files
+
+Debugging exit codes
+--------------------
+Non zero exit codes are used to indicate that the program exited due to an error.
+There are multiple ways to debug this. You could run the program with more verbose logging::
+
+    mpsd-software -l debug ...
+
+Here is a list of exit codes and what they mean:
++-----------+------------------------------------------+----------------------------------------------------------------------------------+
+| Exit code | Reason                                   | Solution                                                                         |
++===========+==========================================+==================================================================================+
+| 10        | Call of 'archspec cpu' failed            | Please install archspec, for example via 'pipx install archspec'                 |
+| 20        | Requested package set is not available   | Use 'available' command to see list of available package_sets                    |
+| 30        | Current directory is already initialised | Check if you are in the  right directory                                         |
+| 40        | Current directory is not initialised     | Check if you are in the  right directory, if so use 'init' command to initialise |
++-----------+------------------------------------------+----------------------------------------------------------------------------------+
diff --git a/src/mpsd_software_manager/mpsd_software.py b/src/mpsd_software_manager/mpsd_software.py
index eed840acf110bd2106401617a7ca3bf3634d300d..442cc8da22a7d7784a3626689250b05d51a467cd 100755
--- a/src/mpsd_software_manager/mpsd_software.py
+++ b/src/mpsd_software_manager/mpsd_software.py
@@ -830,7 +830,7 @@ def get_native_microarchitecture():
             msg += "Documentation of package: https://archspec.readthedocs.io/"
 
             logging.error(msg)
-            sys.exit(1)
+            sys.exit(10)
         else:  # we have found archspec and executed it
             if process.returncode == 0:  # sanity check
                 microarch = process.stdout.strip()
@@ -919,7 +919,7 @@ def install_environment(
             msg += f" in release {mpsd_release}. "
             msg += "Use 'available' command to see list of available package_sets."
             logging.error(msg)
-            sys.exit(1)
+            sys.exit(20)
 
     # Install the package_sets
     with os_chdir(package_set_dir):
@@ -1104,7 +1104,7 @@ def initialize_environment(root_dir: Path) -> None:
         logging.getLogger("print").info(
             f"Error: Directory {str(root_dir)} is already initialized."
         )
-        sys.exit(1)
+        sys.exit(30)
     else:
         # create the init file
         init_file.touch()
@@ -1162,7 +1162,7 @@ def get_root_dir() -> Path:
         + f"and the hidden file `{config_vars['init_file']}`."
         " to check if a directory is initialised"
     )
-    sys.exit(1)
+    sys.exit(40)
 
 
 def main():
diff --git a/tests/test_mpsd_software.py b/tests/test_mpsd_software.py
index 79fc35cea3ee48a3f7f625abd3495bd607bcf51c..1d2a26ef5f68f4161a76d5986b98c688f63f34c0 100644
--- a/tests/test_mpsd_software.py
+++ b/tests/test_mpsd_software.py
@@ -192,7 +192,7 @@ def test_record_script_execution_summary(tmp_path):
 
 def test_install_environment_wrong_package_set(tmp_path):
     """Test exception is raised for non-existing package_set."""
-    # exits with exit code 1 when wrong package_sets are provided
+    # exits with exit code 20 when wrong package_sets are provided
     with pytest.raises(SystemExit) as e:
         mod.install_environment(
             mpsd_release="dev-23a",
@@ -200,7 +200,7 @@ def test_install_environment_wrong_package_set(tmp_path):
             root_dir=(tmp_path),
         )
     assert e.type == SystemExit
-    assert e.value.code == 1
+    assert e.value.code == 20
 
 
 def test_install_environment_wrong_mpsd_release(tmp_path):
@@ -532,21 +532,21 @@ def test_initialize_environment(tmp_path):
     with open(log_file, "r") as f:
         assert (f"Initialising MPSD software instance at {tmp_path}") in f.read()
 
-    # test that calling again results in warning and exit code 1
+    # test that calling again results in warning and exit code 30
     with pytest.raises(SystemExit) as pytest_wrapped_e:
         mod.initialize_environment(tmp_path)
     assert pytest_wrapped_e.type == SystemExit
-    assert pytest_wrapped_e.value.code == 1
+    assert pytest_wrapped_e.value.code == 30
 
 
 def test_get_root_dir(tmp_path):
     """Test that the root directory is correct."""
     with mod.os_chdir(tmp_path):
-        # test that  function exists with error 1 if root dir doesn't exist
+        # test that  function exists with error 40 if root dir doesn't exist
         with pytest.raises(SystemExit) as pytest_wrapped_e:
             mod.get_root_dir()
         assert pytest_wrapped_e.type == SystemExit
-        assert pytest_wrapped_e.value.code == 1
+        assert pytest_wrapped_e.value.code == 40
 
         # test that initialize_environment creates the root dir
         mod.initialize_environment(tmp_path)