34.2 Understanding stanc3 errors and warnings

This is an old version, view current version.

34.2 Understanding stanc3 errors and warnings

During model compilation, stanc can produce a variety of errors (issues that prevent the model from being compiled) and warnings (non-fatal issues that should still be considered).

34.2.1 Warnings

Even without the optional --warn-pedantic and --warn-uninitialized command line flags, both of which enable additional warnings, stanc can still produce warnings about your program. In particular, warnings will be produced in two situations

A completely blank Stan program will produce the following warning message

Warning: Empty file 'empty.stan' detected;
    this is a valid stan model but likely unintended!

The use of any deprecated features will lead to warnings which will look as follows

Warning in 'deprecated.stan', line 2, column 0: Comments beginning with # are
 deprecated and this syntax will be removed in Stan 2.32.0. Use // to
 begin line comments; this can be done automatically using stanc
 --auto-format

A single Stan program can produce many warnings during compilation.

34.2.2 Errors

Errors differ from warnings in their severity and format. In particular, errors are fatal and stop compilation, so at most one error is displayed per run of stanc.

There are four kinds of errors emitted by stanc3

File errors occur when the file passed to stanc is either missing or cannot be opened (i.e. has permissions issues). They look like
```
Error: file 'notfound.stan' not found or cannot be opened
```
Syntatic errors occur whenever a program violates the Stan language’s syntax requirements. There are three kinds of errors within syntax errors; “lexing” errors mean that the input was unable to be read properly on the character level, “include” errors which occur when the #include directive fails, and “parsing” errors which result when the structure of the program is incorrect.
- The lexing errors occur due to the use of invalid characters in a program. For example, a lexing error due to the use of $ in a variable name will look like the following.
```
Syntax error in 'char.stan', line 2, column 6, lexing error:
-------------------------------------------------
  1:  data {
  2:     int $ome_variable;
             ^
  3:  }
-------------------------------------------------
Invalid character found.
```
- When an include directive is used, it can lead to errors if the included file is not found, or if a file includes itself (including a recursive loop of includes, such as A -> B -> A).
```
Syntax error in './incl.stan', line 1, column 0, included from
'./incl.stan', line 1, column 0, included from
'incl.stan', line 1, column 0, include error:
-------------------------------------------------
  1:  #include <incl.stan>
      ^
-------------------------------------------------
File incl.stan recursively included itself.
```
- It is much more common to see parsing errors, which tend to have more in-depth explanations of the error found. For example, if a user forgets to put a size on a type like vector, as in the following, this raises a parsing (structural) error in the compiler.
```
Syntax error in vec.stan', line 3, column 10 to column 11, parsing error:
-------------------------------------------------
  1:  data {
  2:     int<lower=0> N;
  3:     vector x;
                ^
  4:  }
-------------------------------------------------
"[" expression "]" expected for vector size.
```

Semantic errors (also known as type errors) occur when a program is stuctured correctly but features an error in the type rules imposed by the language. An example of this is assigning a real value to a variable defined as an integer.

Semantic error in 'type.stan', line 2, column 3 to column 15:
-------------------------------------------------
  1:  transformed data {
  2:     int x = 1.5;
         ^
  3:  }
-------------------------------------------------
Ill-typed arguments supplied to assignment operator =: lhs has
type int and rhs has type real

Finally, the compiler can raise an internal error. These are caused by bugs in the compiler, not your model, and we would appreciate it if you report them on the stanc3 repo with the error message provided. These errors usually say something like “This should never happen,” and we apologize if they do.