Logback Error Codes

## Logback error messages and their meanings

### The contextSelector cannot be null in `StaticLoggerBinder`.

An `IllegalStateException` is thrown when no ContextSelector could be set for logback's `StaticLoggerBinder`. In principle, this error can only occur when the context selector is expressly specified by the user, and when that context selector cannot not be instantiated correctly.

It should not happen when you are using the default or JNDI context selectors.

### This appender no longer admits a layout as a sub-component, set an encoder instead.

As of logback version 0.9.19, the `WriterAppender` class has been renamed as `OutputStreamAppender`, with `FileAppender` now sub-classing the latter. `OutputStreamAppender` and sub-classes now take an `Encoder` as a sub-component instead of a `Layout`.

In practical terms, this means that configuration files need to be changed

from (DEPRECATED)

    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
      <file>testFile.log</file>
      ...
      <layout class="ch.qos.logback.classic.PatternLayout">
        <pattern>%msg%n</pattern>
      </layout>
    </appender>

or the shorter equivalent (DEPRECATED)

    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
      <file>testFile.log</file>
      ...
      <!-- layout are assigned the type ch.qos.logback.classic.PatternLayout by default -->
      <layout>
        <pattern>%msg%n</pattern>
      </layout>
    </appender>

to (GOOD)

    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
      <file>testFile.log</file>
      ...
      <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
        <pattern>%msg%n</pattern>
      </encoder>
    </appender>

or the shorter equivalent (GOOD)

    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
      <file>testFile.log</file>
      ...
      <!-- encoders are assigned the type
           ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
      <encoder>
        <pattern>%msg%n</pattern>
      </encoder>
    </appender>

For layout type other than `PatternLayout`, for example `HTMLLayout`, your configuration files need to be changed

from (DEPRECATED)

    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
      <file>testFile.log</file>
      ...
      <layout class="ch.qos.logback.classic.html.HTMLLayout">
        <pattern>%msg%n</pattern>
      </layout>
    </appender>

to (GOOD)

    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
      <file>testFile.log</file>
      ...
      <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
        <layout class="ch.qos.logback.classic.html.HTMLLayout">
          <pattern>%msg%n</pattern>
        </layout>
      </encoder>
    </appender>

We hope to make up for this inconvenience with cool new features which are only possible using encoders. During a transition period, layouts passed as parameter will be automatically wrapped by an encoder so that configuration files in the old format (using a layout instead of encoder) will continue to work unmodified.

### No remote host or address is set for `SocketAppender`

A remote host or address is mandatory for SocketAppender.

You can specify the remote host in the configuration file as follows.

    <appender name="SOCKET"
      class="ch.qos.logback.classic.net.SocketAppender">
      ...
      <remoteHost>127.0.0.1</remoteHost>
      ...
    </appender>

### No remote port is set for `SocketAppender`

A remote port is mandatory for SocketAppender.

You can specify the remote port in the configuration file like this:

    <appender name="SOCKET" class="ch.qos.logback.classic.net.SocketAppender">
      ...
      <port>4560</port>
      ...
    </appender>

### No `Layout` is set for SMTPAppender

A `Layout` is mandatory for `SMTPAppender`. It allows SMTPAppender to format logging events before sending an email.

You can specify the `Layout` in a configuration file as follows:

    <appender name="SMTP" class="ch.qos.logback.classic.net.SMTPAppender">
      ...
      <layout class="ch.qos.logback.classic.PatternLayout">
        <pattern>%date [%thread] %-5level %logger - %msg%n"></pattern>
      </layout>
      ...
    </appender>

SMTPAppender is known to work well with PatternLayout and HTMLLayout.

### Specified number is not in proper int form, or not expected format.

When you specify the MaxFileSize to be used by the SizeBasedRollingPolicy, logback expects a rather precise format:

- The number has to be an integer
- You can add 'KB', 'MB' or 'GB' after the number.

Here are some correct values: 500KB, 15MB, 2GB.

### No `TriggeringPolicy` was set for the `RollingFileAppender`.

The `RollingFileAppender` must be set up with a `TriggeringPolicy`. It permits the Appender to know when the rollover must be activated.

To find more information about `TriggeringPolicy` objects, please read the following javadocs:

- `SizeBasedTriggeringPolicy`
- `TimeBasedRollingPolicy`

Please note that the `TimeBasedRollingPolicy` is a TriggeringPolicy and and `RollingPolicy` at the same time.

### Missing integer token, that is %i, in FileNamePattern [...].

The %i conversion token is mandatory for size and time based archiving. In case the %i token is missing, `SizeAndTimeBasedFNATP` attached to `RollingFileAppender` will detect the omission and will not start.

### No `RollingPolicy` was set for the `RollingFileAppender`.

The `RollingFileAppender` must be set up with a `RollingPolicy`. It permits the Appender to know what to do when a rollover is requested.

To find more information about `RollingPolicy` objects, please read the following javadocs:

- `FixedWindowRollingPolicy`
- `TimeBasedRollingPolicy`

Please note that the `TimeBasedRollingPolicy` is a `TriggeringPolicy` and and RollingPolicy at the same time.

### The FileNamePattern property is mandatory for both `TimeBasedRollingPolicy` and `FixedWindowRollingPolicy`.

The FileNamePattern property for both `TimeBasedRollingPolicy` and `FixedWindowRollingPolicy` is mandatory.

Please refer to the documentation of TimeBasedRollingPolicy and FixedWindowRollingPolicy for examples.

### The File property must be set before any rolling policy or triggering policy.

The File property, if present, must be placed before any rolling policy or triggering policy. Thus, in a configuration file, the File property, if present, must be declared declared before any rolling policy or triggering policy declarations.

### File property collides with fileNamePattern. Aborting.

When the file property matches the regular expression defined by fileNamePattern, there is a risk of collision. A collision occurs when the active log file as defined by the file property has the same path as an existing log archive. Such a collision will result in the log archive being overwritten.

As such, in case file property matches the regular expression defined by fileNamePattern, in order to avoid data loss, `RollingFileAppender` will emit an error message and refuse to start.

### The date format in fileNamePattern will result in collisions in the names of archived log files.

This error message is output when the date time pattern in the %d token within the fileNamePattern is not collision free. For example, the following code>fileNamePattern will result in the same log archive every day of the week after the first week of the month.

    myapp-%d{yyyy-MM-uu}.log.zip

As such collisions will result in log data loss, `RollingFileAppender` will check for a variety of such possible collisions and will not start if any collisions are detected.

### File/FileNamePattern option has the same value "..." as that given for appender [...] defined earlier.

If a `FileAppender`/`RollingFileAppender` defined earlier has the same File option as the current appender, then those two appenders are in collision as `FileAppender` instances cannot share the same output target. To prevent loss of data, the current appender will not start. Make sure that each appender has a unique File option.

By analogy the same restriction applies to the FileNamePattern option of RollingFileAppender. Make sure that each RollingFileAppender has a unique FileNamePattern option

### Failed to rename file [x] as [y].

On Windows

On the Windows platform a log file cannot be renamed if there are handles referencing it. For example, when the file is read by another process such as `less`, `tail`, etc. During application hot-redeployment, the old instance of the application will have open references to log files until the old instance is completely shutdown or until the `stop()` method on its `LoggerContext` is invoked.

Process Explorer can help you locate the processes which reference a given file (Find -> Find Handle or DLL). On Linux, you can use the `lsof pathToFile` command to find which process has the file given by pathToFile open.

Rolling might also fail due to incorrect file permission settings. On windows, renaming a file requires the "modify" permission which is different than the permission to "write" to the file.

File rename operations during rollover can be avoided altogether by omitting the file property in RollingFileAppender.

In practice, it can be hard to set the right permissions or to ensure that there are no file handle references to log files.

Under many circumstances, it can be more robust to avoid file renaming during rollover altogether. This is as easy as omitting the file property in `RollingFileAppender`, as shown in the next configuration snippet.

    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
      <!-- file property left unset/blank -->
      <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
        <fileNamePattern>mylog.%d{yyyy-MM-dd}.log</fileNamePattern>
      </rollingPolicy>

      <encoder>
        <pattern>%relative [%thread] %level %logger - %msg%n</pattern>
      </encoder>
    </appender>

Note that for `FixedWindowRollingPolicy`, the file property is mandatory.

#### On Unix-*

On the Unix platform, the basic/quick rename method supplied by the JDK does not work if the source and target files are located on different file systems. In order to deal with this contingency, logback will resort to renaming by copying if all of the following three conditions are met:

1. quick renaming fails,
2. source and destination files for the rename are on different file systems,
3. the host JVM platform runs Java 7 or later.

The code for determining the file system of a file requires Java 7. No rename by copying will be performed on Java 6 or earlier.

As explained in the Windows section above, renaming can be avoided altogether by omitting the file property.

### The File property must be set before `FixedWindowRollingPolicy`

The File property is mandatory with `FixedWindowRollingPolicy`. Moreover, the File option must be set before the `FixedWindowRollingPolicy` element.

Refer to the logback manual on FixedWindowRollingPolicy for more information.

### Prudent mode is not supported with `FixedWindowRollingPolicy`.

Given that `FixedWindowRollingPolicy` performs multiple file rename operations during roll over, and that these operations cannot be guaranteed to be safe in a multi-JVM context, prudent mode is not allowed in conjunction with a `FixedWindowRollingPolicy`.

### SyslogAppender does not admit a layout.

Given that the format of a syslog request follows strict rules, you cannot freely specify the layout to be used with SyslogAppender. However, you can use SuffixPattern option instead to influence the contents of the message sent to the syslog daemon.

For more information on SyslogAppender please refer to the its documentation.

### Only and only one appender can be nested the <sift> element in `SiftingAppender`.

SiftingAppender admits one and only one nested appender.

### Could not find Janino library on the class path. Skipping conditional processing.

Conditional processing in configuration files requires the Janino library. See the setup instructions for adding Janino to your class path.

### As of logback version 0.9.28, JaninoEventEvaluator expects Java blocks.

As of logback version 0.9.28, JaninoEvaluator expects Java "block", i.e. the body of a method. In previous versions only boolean expressions were allowed. For backward compatibility reasons, whenever logback sees a boolean expression it will attempt to convert it to a block by prefixing the expression with "return" and suffixing it with a semicolon.

Boolean expressions can quickly become hairy. For example, the following boolean expression is rather difficult to grok.

     !logger.startsWith("org.apache.http")
      ||
      ( logger.equals("org.apache.http.wire")  &&
           (mdc != null && mdc.get("entity") != null
             &&
           ((String) mdc.get("entity")).contains("someSpecialValue"))
           &&
         !message.contains("someSecret")
      )

whereas as its Java block equivalent is considerably easier to follow.

    if(logger.startsWith("org.apache.http"))
      return true;

    if(mdc == null || mdc.get("entity") == null)
      return false;

    String payee = (String) mdc.get("entity");

    if(logger.equals("org.apache.http.wire") &&
      payee.contains("someSpecialValue") &&
      !message.contains("someSecret")) {
      return true;
    }

    return false;

### In a conversion pattern, opened parenthesis must be closed.

In conversion patterns, parentheses are special because they are treated as grouping tokens. If a parenthesis character needs to be viewed as a literal, it needs to be escaped by preceding each parenthesis with a backslash. As in, \(%d{HH:mm:ss.SSS} [%thread]\) .

### Appenders must be definied before they are referenced.

In a configuration file, at the point where an appender is referenced by name, it must be defined earlier in the configuration file. Referencing an appender defined later in the file is not allowed. Below are examples of correct and incorrect order of definition and referece.

Below is an example of a correct ordering, where appender definition precedes references made to it.

CORRECT ORDER

    <configuration>
      <!-- definition of appender STDOUT -->
      <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
          <pattern>%-4relative [%thread] %-5level %logger{35} - %msg %n</pattern>
        </encoder>
      </appender>

      <root level="DEBUG">
        <!-- appender referenced after it is defined -->
        <appender-ref ref="STDOUT"/>
      </root>
    </configuration>

Below is an example of an incorrect ordering, where appender definition follows references made to it.

INCORRECT ORDER

    <configuration>
      <root level="DEBUG">
        <!-- appender INCORRECTLY referenced before it is defined -->
        <appender-ref ref="STDOUT"/>
      </root>

      <!-- definition of appender STDOUT -->
      <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
          <pattern>%-4relative [%thread] %-5level %logger{35} - %msg %n</pattern>
        </encoder>
      </appender>
    </configuration>