# This is **init.sh** error fixing documentation

This document do not pretend to be exhaustive but will cover all errors that can
be returned by libraries and some basic modules. It will not cover errors
generated by external programs or Bash itself. Please refer to corresponding
documentation in such situation.

## Error #1: Command line syntax error or incompatible options
You've called the **init.sh** script with command line syntax error or options
that are not compatible together. Some options exclude each others or trigger
opposite events.

To fix it check your command line taking into account of the detailled error
message displayed together with that error.

## Error #2: Misuse of Bash built-in
A Bash builtin function is uncorrectly called.

If that error happens on the execution of a module you made yourself, you might
check the code of your module and fix what goes wrong.

If it happens on the execution of **init.sh** or a builtin module, please send a
bug repport.

## Error #3: Missing library file or function
One of the internal vital function of **init.sh** is missing.

Most of the time that error happens when one of the library files of **init.sh**
is missing. Please check your directory tree and all files are available. Use
git as a reference if you have some doubts.

If you have all the files, make sure they are not truncated (it can happens, for
example, if disk is full), that you use consistant versions (yet again, git is
the reference) or you didn't modified something accidentally in libraries or
**init.sh** script.

## Error #4: No root right
You tried to execute **init.sh** without administrative rights.

As **init.sh** goal is to transform system, administrative rights are absolutely
necessary. To fix this, run **init.sh** as superuser, using ```sudo``` or
```su```.

If you run as non UID #0 user but you're certain to have all the necessary
rights, you have to use the ```--no-check-root``` option.

## Error #5: Malformed module list
The module list you provided is malformed or contains forbidden characters.

To fix this, check your module list in your configuration file or in your
command line if you passed it manually. If you created a module you added in the
list, make sure your module does not contain a dash '-' character, or any non
alphanumeric character other than underscore. If you use a number in your module
name, make sure it's not begining with.

## Error #6: Unable to find configuration
That error happens when no configuration file suitable for your machine have
been found.

To fix this, make sure you have a configuration file named after the lowercase
hostname of the computer you run on in the ```conf/``` directory of your
**init.sh** tree. Alternatively you can use a generic file named
```init.conf.sh``` in that same directory.

If you gave manual configuration files, check they all exists.

## Error #7: Misuse of script internal function
One of the base function of **init.sh** libraries is not being used correctly.

If that error happens while executing one of your module, please check your code
especially when you use a **init.sh** internal. The
[developper documentation](dev.md) will help you about synthax.  Check your
parameters are correctly passed in the good format and do not use wildcards in
file names.

If it happens on the execution of **init.sh** or a builtin module, please send a
bug repport.

## Error #8: Can't determine OS type or version
As **init.sh** relies on some specific operating system commands (like package
manager) the detection system must be able to obtain OS characteristics.

To fix this you must check the ```/etc/os-release``` file availability for your
distribution. If your distribution do not provide that file, you'll have to
create it yourself providing on the bare minimum an ``ID`` entry. Check the
[```/etc/os-release``` file documentation](https://www.freedesktop.org/software/systemd/man/os-release.html)
for details.

## Error #9: Unsatisfied dependency
That error can happens in two cases scenario. One case is one or more of your
modules depends on another which is not part of the module to execute. The other
case is when you call a module too early.

To fix this, check your module list order. Check also your modules dependenies
are in the list before they are called themself.

If you wrote your own module, make sure you have no circular dependencies.

## Error #10: File missing or empty
You have refered a file that don't exists or is empty, if the file is required
to have a content.

Check your filename and path in modules and/or configuration files.

## Error #11: Bad function call
That error is trigered when an internal function is called with a wrong number
of parameters.

If that error happens while executing one of your module, please check your code
especially when you use a **init.sh** internal. The
[developper documentation](dev.md) will help you about synthax.

If it happens on the execution of **init.sh** or a builtin module, please send a bug
repport.

## Error 12: Error copying files
A file copy opperation have failed.

Make sure your source path exists and is readable and destination is writable
and target directory exists. Chack also if target do not contain a symbolic link
or a directory with the same name.

## Error #13: Bad target file system
The target file system you provided is not part of the root filesystem, is not
accessible or is not an absolute path.

Make sure your destination paths are fully qualified paths names (begining with
"/"), is writable and the destination path exists.

## Error #14: Impossible to chroot
That error occurs when the chroot target don't exists.

Check your target filesystem, make sure it's mounted.

## Error #15: Bad chrooted installation, destination OS needs to be fixed
The target installation is incomplete or not usable in a chrooted environment.

Check all the filesystems needed to perform the chroot are mounted correctly. If
your target installation is damaged, you have to fix it before running
**init.sh**.

## Error #16: Invalid options provided with cron mode activated
When cron mode is on, **init.sh** support a very limited range of options.

To fix this, don't use the ```--check-only``` or ```--jump``` options when using
cron mode.

## Error #17: Missing or invalid status file, can't resume
You asked to resume on last error, but no status file can be found.

To fix this, remove the ```--resume``` option. You can use the ```--modules```
option instead to ask for a limited range of modules.

## Error #50 to #100: Error in module execution
A module trigered an internal error while executing change to the system. You
need to check the concerned module documentation.

As the module may have done some unfinished changes to the system, it will be
safer to resume after fixing the problem before rebooting.

## Error #126: Command exists but is not executable
You try to execute a command that is not executable for you.

Check your rights to execute the so said command. Check also the excutable is
valid if the command is external.

## Error #127: Command not found
You try to call a command that do not exists.

If taht error comes from one of your modules, check the spelling of the
command. Check also if the program you need is installed and think about
installing it through the provided **init.sh** builtin functions.

If that occurs with a builtin module or in **init.sh** code or libraries please
fill a bug repport.

## Error #128: Abortion due to external cause
That error happens when an exeternal signal is triggering a stop in the
execution of **init.sh**.

Do not halt or restart the computer before the end of **init.sh** execution.
Using Ctrl + C sequence or the kill command on the bash process running the
script will lead to that error too.

## Error #150 to #200: Error in module checks
One of the checks executed prior **init.sh** actions did not pass.

To resolve this, fix the condition of execution of your module as explained in
the associated error message.

## Error #255: Exit status out of range
That error is a special case when the exit status of a program is above 255 as
authorized by many high level programming languages.

Check the error in the program emiting it and the associated program
documentation.

-----------------------------------------------------------------------------
Documentation (c) 2019-2021 Geoffray Levasseur.

This file is distributed under3-clause BSD license. The complete license
agreement can be obtained at: https://opensource.org/licenses/BSD-3-Clause