\label{doc_dev_error-categorization_md_md_doc_dev_error_categorization}%
\Hypertarget{doc_dev_error-categorization_md_md_doc_dev_error_categorization}%
 This document explains how to categorize errors and should act as a form of guideline. The categorization aims to reduce duplicated errors and the maintenance effort for errors.\hypertarget{doc_dev_error-categorization_md_autotoc_md2139}{}\doxysection{Categorization Mindset}\label{doc_dev_error-categorization_md_autotoc_md2139}
Errors along with their unique code only primarily exist because they can be {\bfseries{reacted differently on programmatically}}. To get an idea of programmatic reactions take a method call which returns a {\ttfamily Timeout} error. Naturally a senseful reaction would be to retry at a later point in time. So the reaction here would be to retry with a time based approach. On the other hand it does not make sense to differentiate between {\ttfamily No Write Permission} and {\ttfamily No Read Permission} as the application just knows that it simply cannot access the desired resource and tells the user to grant it.

Categories are hierarchically structured. In some categories you cannot put an error such as {\ttfamily Permanent errors} (see below) because they are too general and developers should choose a more specific category. Even though most categories which allow to put errors into are at the end of the hierarchy (leafs), it may also be the case that a more general category also allows errors to be put in (e.\+g., {\ttfamily Resource Errors}). The categories below are marked as {\ttfamily concrete} or {\ttfamily abstract}, meaning that you either can or cannot create errors for the category. Please choose the most specific category as possible when trying to assign an error to a category.

If you feel for a new category, please forge a design decision document and make a PR to Elektra\textquotesingle{}s repo.\hypertarget{doc_dev_error-categorization_md_autotoc_md2140}{}\doxysection{Error categorization Guideline}\label{doc_dev_error-categorization_md_autotoc_md2140}
Now we will investigate each category in more detail and when to put an error/warning in there.

For a complete structural overview please visit the corresponding \mbox{\hyperlink{doc_decisions_error_codes_md}{design}}decision document"{}\hypertarget{doc_dev_error-categorization_md_autotoc_md2141}{}\doxysubsection{Permanent errors (\char`\"{}\+C01000\char`\"{}, abstract)}\label{doc_dev_error-categorization_md_autotoc_md2141}
The branch category {\ttfamily Permanent Errors} refer to such errors which cannot be fixed by retry at all. {\ttfamily Permanent Errors} are subdivided into


\begin{DoxyItemize}
\item Resource
\item Installation
\item Logical
\end{DoxyItemize}\hypertarget{doc_dev_error-categorization_md_autotoc_md2142}{}\doxysubsubsection{Resource (\char`\"{}\+C01100\char`\"{}, concrete)}\label{doc_dev_error-categorization_md_autotoc_md2142}
{\ttfamily Resource Errors} are all kind of permission, existence and resource errors which are essential for Elektra to operate. Resource errors is a branch category which also allows for errors to be put in. Compared to validation errors this category has its focus the underlying system resources whereas validation errors for usages with specifications. Examples are missing files/ directories or insufficient permission to execute certain commands (eg. you would require sudo permissions). Reactions are fixing the permissions, remount, creating the file/directory and retry the operation. Compared to validation errors, administrators would change the specification or retry with a different value.\hypertarget{doc_dev_error-categorization_md_autotoc_md2143}{}\doxyparagraph{Out of Memory (\char`\"{}\+C01110\char`\"{}, concrete)}\label{doc_dev_error-categorization_md_autotoc_md2143}
{\ttfamily Out of Memory Errors} are special resource errors which come from failed {\ttfamily elektra\+Malloc} calls primarily as no more memory could be allocated for the application. Errors with not enough hard disc space do not belong here but into {\ttfamily Resource}. Such errors will gain special handling in future releases and users cannot deal with such errors as of now.\hypertarget{doc_dev_error-categorization_md_autotoc_md2144}{}\doxysubsubsection{Installation (\char`\"{}\+C01200\char`\"{}, concrete)}\label{doc_dev_error-categorization_md_autotoc_md2144}
{\ttfamily Installation Errors} are errors that are related to a wrong installation such as wrong plugin names, missing backends, initialization errors, misconfiguration of Elektra etc. Installation errors might also be non-\/\+Elektra specific but also from dependent library/applications such as gpg. Also plugin configuration errors belong to {\ttfamily Installation Errors} as this happens during mounting. Users will have to reconfigure, reinstall, recompile (with other settings) Elektra in order to get rid of this error or fix the installation of the corresponding library/application.\hypertarget{doc_dev_error-categorization_md_autotoc_md2145}{}\doxysubsubsection{Logical (\char`\"{}\+C01300\char`\"{}, abstract)}\label{doc_dev_error-categorization_md_autotoc_md2145}
{\ttfamily Logical Errors} is a branch category in which you indicate a logical flaw in the code such as internal errors, not implemented features, passing illegal parameters to functions, plugins which do not behave accordingly (wrong return codes, uncaught exceptions) or errors which should not happen such as going into a {\ttfamily default} branch when you are assured that all cases are covered. Usually such errors come with a message to report such failures to Elektra\textquotesingle{}s bugtracker. Applications cannot handle such errors themselves.\hypertarget{doc_dev_error-categorization_md_autotoc_md2146}{}\doxyparagraph{Internal (\char`\"{}\+C01310\char`\"{}, concrete)}\label{doc_dev_error-categorization_md_autotoc_md2146}
{\ttfamily Internal Errors} are such errors which indicate a flaw or bug in the internal logic of Elektra. Examples are going into a {\ttfamily default} branch which you do never expect to happen. Another use case is if you use an external library and have to catch a generic exception. If you can however, catch the most specific exceptions and convert them into the appropriate category. If you have to use this error please add a message indicating that this bug should be reported.\hypertarget{doc_dev_error-categorization_md_autotoc_md2147}{}\doxyparagraph{Interface (\char`\"{}\+C01320\char`\"{}, concrete)}\label{doc_dev_error-categorization_md_autotoc_md2147}
{\ttfamily Interface Errors} indicate a wrong usage of Elektra\textquotesingle{}s API. Compared to {\ttfamily internal} errors this category does not indicate a bug but a misuse. An example would be to pass a NULL pointer to {\ttfamily kdb\+Get}. Also violations of the backend belong into this category. Compared to semantic validation errors, this category has its focus on detecting wrong usages of the API instead of a \char`\"{}retry with a different value\char`\"{} approach. Also validation errors focus on specifications of configurations whereas this category tries to handle specifications for APIs. Users should investigate the concrete reason and might use a different, more appropriate method or change their passed values before retrying.\hypertarget{doc_dev_error-categorization_md_autotoc_md2148}{}\doxyparagraph{Plugin Misbehavior (\char`\"{}\+C01330\char`\"{}, concrete)}\label{doc_dev_error-categorization_md_autotoc_md2148}
{\ttfamily Plugin Misbehavior Errors} indicate that a plugin does not behave in an intended way. Unrecognized commands, unknown return codes, plugin creation errors, etc. belong to this category. Also uncaught exceptions belong here because Elektra expects all exceptions to be caught. For wrong plugin versions please use {\ttfamily Installation} errors. Users can try to remount, recompile the plugin under different options or use a different plugin (e.\+g., switching to {\ttfamily mini} instead of {\ttfamily ini}).\hypertarget{doc_dev_error-categorization_md_autotoc_md2149}{}\doxysubsection{Conflicting State (\char`\"{}\+C02000\char`\"{}, concrete)}\label{doc_dev_error-categorization_md_autotoc_md2149}
{\ttfamily Conflicting State Errors} are errors where the current state is incompatible with the attempted operation. These kind of errors are usually in resolver plugins when the state of the file has changed without the system knowing. An example would be to try to push your changes into a git repository where the remote branch has already changed. Try to synchronize your internal state and retry to get rid of this error. Examples are the need for calling {\ttfamily kdb\+Get} before {\ttfamily kdb\+Set}.\hypertarget{doc_dev_error-categorization_md_autotoc_md2150}{}\doxysubsection{Validation (\char`\"{}\+C03000\char`\"{}, abstract)}\label{doc_dev_error-categorization_md_autotoc_md2150}
{\ttfamily Validation Errors} are heavily used for Elektra\textquotesingle{}s {\ttfamily configuration specification} feature and should tell users that their given input does not match a certain pattern/type/expected semantic etc.

Validation errors can either be syntactic or semantic.\hypertarget{doc_dev_error-categorization_md_autotoc_md2151}{}\doxysubsubsection{Syntactic (\char`\"{}\+C03100\char`\"{}, concrete)}\label{doc_dev_error-categorization_md_autotoc_md2151}
{\ttfamily Syntactic Errors} are errors which tell users or applications that the current format is not valid. Examples are wrong date formats or missing closing brackets {\ttfamily \mbox{]}} inside of a regular expression when it is checked. Also path related errors like missing slashes come into this category. Parsing errors are also associated with syntactic errors such as unexpected encounters like missing line endings, illegal characters or wrong encodings. Also transformation and conversion errors are to be categorizes here because the format of the given input does not allow such actions. Since syntactic errors demand a specific format and structure, also structural validation errors belong here. Users should try a different value/format and retry setting it with Elektra.\hypertarget{doc_dev_error-categorization_md_autotoc_md2152}{}\doxysubsubsection{Semantic (\char`\"{}\+C03200\char`\"{}, concrete)}\label{doc_dev_error-categorization_md_autotoc_md2152}
{\ttfamily Semantic Errors} are errors which indicate a misunderstanding of the intended meaning between a user\textquotesingle{}s/developer\textquotesingle{}s/administrator\textquotesingle{}s way of seeing a setting and the application\textquotesingle{}s one. The main focus of this category is to enforce specifications compared to other categories. So if users provide input which do not match prespecified criterias even though syntactically everything is valid, this category should be used. Examples are references to non-\/existent keys ({\ttfamily reference} plugin), setting values to keys which require to be empty ({\ttfamily required} plugin), wrong provided values in a specification if you restricted the values ({\ttfamily enum} plugin), etc.

Users should try a different value or fix the underlying specification and retry again.\hypertarget{doc_dev_error-categorization_md_autotoc_md2153}{}\doxysection{Underlying design decision document}\label{doc_dev_error-categorization_md_autotoc_md2153}

\begin{DoxyItemize}
\item \mbox{\hyperlink{doc_decisions_error_codes_md}{Decision Document}} The underlying design decision document. 
\end{DoxyItemize}