errors.tex

\section{Errors, Warnings, and Infos}\label{sec:errorwarn}

This section explains the most frequent errors, warnings, and info messages
related to inappropriate inputs or command line options.
All messages are printed to the standard error stream.
Errors lead to premature termination,
while warnings and info messages provide hints at possibly corrupt input that can still be processed further.

\subsection{Errors}\label{sec:error}

Most of the errors in the following start with the prefix:
\begin{lstlisting}[numbers=none,escapechar=@]
*** ERROR: (@\textit{System}@)
\end{lstlisting}
where \codeit{System} is either \code{gringo}, \code{clingo}, or \code{clasp} depending on the system.
In the following sections, we use \codeit{Error} to denote this prefix.
All of the errors with this prefix are fatal and lead to immediate termination.

\subsubsection{Parsing Command Line Options}\label{subsec:error:options}

We start with errors emmited during command line parsing,
which are handled equally by \gringo, \clasp, and \clingo.
All our tools try to expand incomplete (long) options to recognized ones.
Parsing command line options may nonetheless fail due to the following three reasons:
%
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Error}@: In context '@\textit{Context}@': unknown option: '@\textit{Option}@'
@\textit{Error}@: In context '@\textit{Context}@': \
ambiguous option: '@\textit{Option}@' could be:
  @\textit{Option1}@
  @\textit{Option2}@
  ...
@\textit{Error}@: In context '<@\textit{Context}@>': \
'@\textit{Arg}@': invalid value for: '@\textit{Option}@'
*** Info : (@\textit{System}@): Try '--help' for usage information
\end{lstlisting}
%
The first error means that the option~\codeit{Option}
could not be expanded to one that is recognized.
While the second error expresses that the result of expanding~\codeit{Option} is ambiguous.
It is followed by a list of option canditates \codeit{Option1}, \codeit{Option2}, \dots, all sharing the same prefix.
Finally, the third error occurs if the argument~\codeit{Arg} is invalid for option~\codeit{Option}.
All three error messages include a context~\codeit{Context} in which the option is parsed.
Often, this is simply the system name 
but can also be the name of a configuration in a portfolio file
or the string \code{tester} for errors in options regarding the disjunctive tester.
The last line is printed in all three cases.
It indicates that option \code{--help} can be used to display the available options and their arguments.

\subsubsection{Parsing and Checking Logic Programs}\label{subsec:error:parselp}

Next, we consider errors emitted during the parsing and checking of logic programs.
Unlike the error messages in the previous section, 
such errors include location information to ease finding and fixing the problem.
Each of the error messages below begins with a location followed by the string \code{error} and a short description of the error in~\codeit{Message}:
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{File}@:@\textit{Line}@:@\textit{Column}@-@\textit{Column}@: error: @\textit{Message}@
  @\textit{Information}@
@\textit{File}@:@\textit{Line}@:@\textit{Column}@-@\textit{Column}@: note: @\textit{Message}@
  @\textit{Information}@
...

\end{lstlisting}
The location refers to a string in a source file,
specified by file name~\codeit{File},
line number~\codeit{Line},
and beginning and ending column number~\code{Column}
(column $n$ refers to the $n$-th symbol in a line).
Error messages are sometimes followed by further desriptions in the string~\codeit{Information} indented by two spaces.
An optional list of similarly structured notes, discernable via the string~\code{note}, can follow this part.
Such notes typically refer to locations that are in conflict with the object referred to in the location of the error message.
Multiple error messages of this kind might be reported;
each error message is terminated with two newlines after the notes.

\paragraph{Logic Program Parsing}
We start our description with errors that may be encountered during parsing,
where the following one indicates a syntax error in the input:
%
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Location}@: error: syntax error, unexpected @\textit{Token}@
\end{lstlisting}
%
To correct this error, please investigate the indicated location
and check whether something looks strange there
(like a missing period, an unmatched parenthesis, etc.).
Note that the parser tries to recover from a syntax error.
This typically means that everything up to the next period is ignored.

\paragraph{Safety Checking}
The next error occurs if an input program is not safe:
%
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Location}@: error: unsafe variables in
  @\textit{Rule}@
@\textit{Location}@: note: '@\textit{Var}@' is unsafe
...
\end{lstlisting}
%
Along with the error message,
the affected rule~\codeit{Rule} and a list of all unsafe variable occurrences~\codeit{Var} are reported.
The first action to take usually consists of checking whether
variable~\codeit{Var} is actually in the scope of any atom
(in the positive body of \codeit{Rule}) that can bind it.%
\footnote{%
  Recall from Section~\ref{subsec:gringo:arith} and~\ref{subsec:gringo:comp}
  that variables in the scope of built-in arithmetic functions are only bound by their corresponding atoms in some special cases 
  and that built-in comparison predicates do not bind variables.}
Also check for variables that occur in aggregate elements (cf.\ Section~\ref{subsec:gringo:aggregate}) or conditional literals (cf.\ Section~\ref{subsec:gringo:condition});
you might have to bind them with additional positive atoms in the conditions.

\paragraph{Script Execution and Parsing}
If an error in an embedded script occurs (cf.~Section~\ref{subsec:lang:extfun}), the following error message is printed:
%
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Location}@: error: failed to execute script:
  @\textit{Information}@
  ...
\end{lstlisting}
%
The information printed depends on the error that occurred when executing the embedded script.
This can for example be parse errors or errors that occurred when executing the script.
Typically, the information contains a trace where the error occurred.

\paragraph{Defining Constants}
There are three errors associated to \code{\#const} statements (cf.~Section~\ref{subsec:gringo:meta}).
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Location}@: error: cyclic constant definition:
  @\textit{Constant}@
@\textit{Location}@: note: cycle involves definition:
  @\textit{Constant}@
...

@\textit{Location}@: error: redefinition of constant:
  @\textit{Constant}@
@\textit{Location}@: note: constant also defined here:
  @\textit{Constant}@
...

\end{lstlisting}
The strings~\codeit{Constant} provide the affected \code{\#const} statements.
The first error is printed if the statements rely on each other cyclically.
Each statement involved in the cycle is printed in the corresponding notes.
The second error message is printed if a constant is defined more than once.
The location of the conflicting definition is printed in the note.

If at least one of the errors above is reported,
then \gringo\ or \clingo\ terminates after parsing and checking with the error message:
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Error}@: grounding stopped because of errors
\end{lstlisting}

\begin{note}
No more than 20 errors are printed.
If this limit is exceeded, the application stops parsing or safety checking and terminates.
\end{note}

\subsubsection{Parsing Logic Programs in \smodels\ Format}\label{subsec:error:lparse}
The following error message is issued by (embedded) \clasp:
%
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Error}@: parse error in line @\textit{Line}@: @\textit{Message}@
\end{lstlisting}
%
This error means that the input does not comply with \smodels' numerical format~\cite{lparseManual}.
If you are using \gringo\ to ground logic programs,
this error should never occur.

\subsubsection{Multi-shot Solving}
The following error is issued by (embedded) \clasp\ if an atom is defined (it appears in the head of a rule) in two different grounding steps:
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Error}@: redefinition of atom <@\textit{Atom}@,@\textit{Id}@>
  @\textit{Information}@
\end{lstlisting}
where \codeit{Atom} is the string representation of the atom that is redefined
and \codeit{Id} is the unique identifier of the atom introduced when translating the logic program into \smodels\ format.
If the scripting API~(cf.~Section~\ref{sec:multi}) is used for grounding,
then the error message is followed by a trace,
indicating the source code location where the program has been grounded.

\begin{note}
Only the case that an atom is redefined is checked by clasp.
The case when there is a positive cycle over two or more incremental steps is not detected,
which possibly leads to unwanted answer sets.
\end{note}

\subsection{Warnings}\label{subsec:warn}

This section describes warnings that may be reported by \gringo\ or \clingo.
Unlike errors, warnings do not terminate the application 
but rather hint at problems, which should be investigated.
A program with warnings might lead to unexpected results;
there are no guarantees regarding the semantics of such programs.
Most warnings have a similar format as the errors described in Sections~\ref{subsec:error:parselp};
the only difference is that the location is followed by the string \code{warning}.

\begin{note}
No more than 20 warnings are printed.
If this limit is exceeded, you should definitely fix some warnings.
\end{note}

\subsubsection{File Included Multiple Times}\label{sec:warn:incfile}
If a file is included multiple times,
either on the command line or with an include directive,
then the following warning is emitted:
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Location}@: warning: already included file:
  @\textit{Filename}@
\end{lstlisting}

\begin{note}
Only the first include of a file is considered.
All additional includes are ignored.
\end{note}

\subsubsection{Unbounded CSP Variables}\label{sec:warn:unbound}
In the current implementation, a bound has to be supplied for each CSP variable (cf.~Section~\ref{sec:clingcon}).
For variables with bounds, the following warning is issued:
\begin{lstlisting}[numbers=none,escapechar=@]
warning: unbounded constraint variable:
  domain of @\textit{Variable} is set to \textit{Domain}
\end{lstlisting}
where \code{Variable} is the variable lacking a domain specification
and \code{Domain} is an (arbitrary) domain chosen for the variable.

\subsection{Infos}\label{subsec:info}
This section describes information messages
that may be reported by \gringo\ or \clingo.
Info messages indicate issues in the input
that have a well defined semantics
but are possibly unintended by the user.

An information message is preceded with the string \code{info}.

\begin{note}
Up to 20 info messages are printed.
There might me further issues but these will be silently ignored.
\end{note}

\subsubsection{Undefined Operations}\label{sec:warn:undefterm}
These may occur within an arithmetic evaluation (cf.~Section~\ref{subsec:gringo:arith})
or if an error occurs while evaluating an external function (cf.~Section~\ref{subsec:lang:extfun}):
%
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Location}@: info: term undefined:
  @\textit{Term}@
...
\end{lstlisting}
%
It typically means that either a (symbolic) constant or a compound term (over an uninterpreted function)
has occurred in the scope of some built-in arithmetic function.
%
The string~\codeit{Term} provides the term that failed to evaluate.
%
The message might be followed by further notes.
For example, 
if the evaluation of an external function failed,
by a trace indicating the location of the error within the source code of the external function.
%
Typically, it is simple to fix occurrences of this message
- for example, if the term `\code{X/Y}' causes a message,
it can be silenced by adding the comparison literal~`\code{Y!=0}' to the body of a rule (or condition).
We suggest to silence all of these message in this manner
and not simply to disable the message.

\begin{note}
Instantiations of rules, \code{\#show} statements, \code{\#external} statements, weak constraints, aggregate elements, and conditional literals
that contain undefined terms are discarded.
\end{note}

\subsubsection{Undefined Atoms}\label{sec:warn:undefatm}
This message is emitted if an atom appears in the body of a rule or condition
that is never defined in the head of a rule or external statement:
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Location}@: info: atom is undefined:
  @\textit{Atom}@
\end{lstlisting}
%
where \codeit{Atom} is the atom occurrence without a definition.
Often, this message indicates that a predicate has been misspelled 
or that an argument has accidentally been omitted.

\subsubsection{Global Variables in Tuples of Aggregate Elements}\label{sec:warn:global}
This message is emitted if a variable occurs globally in a tuple of an aggregate element:
\begin{lstlisting}[numbers=none,escapechar=@]
@\textit{Location}@: info: global variable in tuple of @\textbackslash@
                aggregate element:
  @\textit{Variable}@
\end{lstlisting}
where \codeit{Variable} is the variable that occurs globally.
Typically, this message occurs if a there is a name clash between a global and a local variable
because in most situations it should not be necessary to put global variables into the tuples of aggregate elements.