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 subcomponent, set an encoder instead.

As of logback version 0.9.19, the WriterAppender class has been renamed as OutputStreamAppender, with FileAppender now subclassing the latter. OutputStreamAppender and subclasses now take an Encoder as a subcomponent 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:

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:

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:

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 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.

Nested <if> element within <appender>, <logger> or <root> elements is disallowed

Ad of logback version 1.3, an <if> element nested within <appender>, <logger> or <root> elements is disallowed and will yield unexpected results.

For example, the following is considered incorrect.


<root level="INFO">
    <appender-ref ref="CONSOLE" />
    <appender-ref ref="FILE" />
    <!-- <if> nested within <root> disallowed -->
    <if condition='isDefined(​"A_VARIABLE")'>
      <then>
        <appender-ref ref="SOME_APPENDER" />
      </then>
    </if>
</root>    
 

However, it can be written with the desired effect as follows.


<root level="INFO">
    <appender-ref ref="CONSOLE" />
    <appender-ref ref="FILE" />
</root>        
<!-- <if> surronding <root> is fine -->
<if condition='isDefined(​"A_VARIABLE")'>
    <then>
        <root>    
            <appender-ref ref="SOME_APPENDER" />
      </root>    
    </then>
</if>

We are of the opinion that nested-if form can always be transfomed into the surrounding-if form.

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;

The <param> element is deprecated in favor of a more direct syntax.

Instead of writing (DEPRECATED)


    <appender name="STDOUT" class="ch.qos.logback.​core.ConsoleAppender">
      <encoder>
        <param name="pattern" value="%logger- %msg %n"/>
      </encoder>
    </appender>
   

prefer the direct form (GOOD)


    <appender name="STDOUT" class="ch.qos.logback.​core.ConsoleAppender">
      <encoder>
        <pattern>%logger - %msg %n</pattern>
      </encoder>
    </appender>
   

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]\) .

Error during SAX parser configuration

If you see the following error is thrown during logback configuration

Caused by: javax.xml.parsers.ParserConfigurationException: SAX feature 'http://xml.org/sax/features/external-general-entities' not supported.
 at oracle.xml.jaxp.​JXSAXParserFactory.​setFeature(JXSAXParserFactory.​java:272)
 at ch.qos.logback.core.​joran.event.SaxEventRecorder.​buildSaxParser(​SaxEventRecorder.​java:82)
   

then we suggest that you specify a SAX parser that supports selective feature enabling/disabling. Try setting the following system property.

-Djavax.xml.parsers.​SAXParserFactory=​com.sun.org.apache.​xerces.internal.​jaxp.SAXParserFactoryImpl

See also LOGBACK-1577.

Appenders must be defined before they are referenced.

The restriction described below has been lifted in logback version 1.3. The description is kept for users of logback 1.2 and earlier.

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 reference.

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>