XML Error Handling

JMRI will sometimes encounter errors loading XML files including layout and control panels. Some of these errors occur when loading a file created in an older version of JMRI that contains data in a format no longer supported or recognized by newer versions of JMRI.

Note It is likely that the first error encountered in an XML document will prevent further errors from being reported. The XML file should probably be reviewed for all errors listed below.

Fixing Errors

Generally these errors can be fixed by opening the XML file in text editor. You can use the text editor included in your operating system, which is often very basic, or another one downloaded from elsewhere. Atom is an XML format aware editor for Windows, macOS, and Linux with that can be used if needed.

Most remediation recommendation in the errors list below assume an ability to edit the file directly.


These errors are in alphabetical order and contain the start of the complete message.

The XML file is attempting load an object for which the code required to create that object (its class) does not exist. There are three possible reasons for this, in order of likelihood:
  1. The class was removed from JMRI. We sometimes remove classes that were replaced by other classes, generally years after the replacement was implemented. The following table is a partial list of these classes with the replacement class and recommended remediation:
    Removed Class Replacement Class Remediation
    jmri.configurexml.AbstractSignalHeadManagerXml jmri.managers.configurexml.AbstractSignalHeadManagerXml Replace instances of removed class with replacement class in file.
  2. The file was generated in a newer version of JMRI than the one being used. The recommended remediation for this is to continue to use the newer version. If that is not possible, seek assistance on the JMRI User's Group.
  3. The class was in a plugin developed by a third party. The plugin will need to be reinstalled, or the contents causing issues will need to be removed. Seek assistance from the developer of that plugin or on the JMRI User's Group.
A NamedBean (i.e. Turnout, Sensor, Logix, Conditional, etc) has an invalid system name. You can often figure out which one it was from the traceback just below the message, which will show the type of "manager" that failed, i.e. a reference to jmri.managers.DefaultSensorManager means that problem was while loading a Sensor. (Problems with Conditionals are often blamed on DefaultLogixManager). Messages right after the traceback will also sometimes show the problematic name.
Parse error
The XML file is not readable for some reason. This can be for one of two reasons:
  1. The file is not valid XML. This could be the result of editing the file to fix another error, or it's being truncated by another process. Seek assistance on the JMRI User's Group.
  2. The file does not conform to the XML schema JMRI requires file to conform to. Specific schema validations and the recommended remediation are:
    Error Remediation
    Attribute "error" must be declared for element type "sensoricon"
    1. Remove the text <!DOCTYPE layout-config SYSTEM "layout-config.dtd">
    2. Replace <layout-config> with <layout-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://jmri.org/xml/schema/layout.xsd">.
    cvc-pattern-valid: Value 'resource:something' is not facet-valid with respect to pattern '(program:|preference:|settings:|home:|profile:|file:|http:|[a-zA-Z]:)[a-z A-Z0-9/\-_\.]*' for type 'urlType'. Replace all instances of resource: in the XML file with program: