{"record":{"id":"14f94762c1f30cbe","repo":"jenkinsci/jenkins","slug":"unable-to-read","errorCode":null,"errorMessage":"Unable to read {}","messagePattern":"Unable to read (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/hudson/XmlFile.java","lineNumber":167,"sourceCode":"    public File getFile() {\n        return file;\n    }\n\n    public XStream getXStream() {\n        return xs;\n    }\n\n    /**\n     * Loads the contents of this file into a new object.\n     */\n    public Object read() throws IOException {\n        if (LOGGER.isLoggable(Level.FINE)) {\n            LOGGER.fine(\"Reading \" + file);\n        }\n        try (InputStream in = new BufferedInputStream(Files.newInputStream(file.toPath()))) {\n            return xs.fromXML(in);\n        } catch (RuntimeException | Error e) {\n            throw new IOException(\"Unable to read \" + file, e);\n        }\n    }\n\n    /**\n     * Loads the contents of this file into an existing object.\n     *\n     * @return\n     *      The unmarshalled object. Usually the same as {@code o}, but would be different\n     *      if the XML representation is completely new.\n     */\n    public Object unmarshal(Object o) throws IOException {\n        return unmarshal(o, false);\n    }\n\n    /**\n     * Variant of {@link #unmarshal(Object)} applying {@link XStream2#unmarshal(HierarchicalStreamReader, Object, DataHolder, boolean)}.\n     * @since 2.99\n     */","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/jenkinsci/jenkins/blob/2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc/core/src/main/java/hudson/XmlFile.java#L149-L185","documentation":"Thrown by XmlFile.read() — which loads an XML file into a new object via XStream (xs.fromXML). Any RuntimeException or Error during deserialization is caught and wrapped in an IOException with the file path. This is the path for reading a config file fresh (not into an existing object).","triggerScenarios":"xs.fromXML(in) throws a RuntimeException — common XStream exceptions include CannotResolveClassException (class referenced in XML not on classpath), ForbiddenFieldException, or ConversionException (field type mismatch, invalid enum value, etc.). An Error (e.g., NoClassDefFoundError) is also caught and wrapped.","commonSituations":"A plugin was uninstalled or renamed, so classes referenced in config.xml can no longer be resolved; XStream annotations or converters changed between versions; config.xml is hand-edited with invalid XML structure or invalid enum values; a class was refactored (renamed/moved) but old XML references the old class name; NoClassDefFoundError from a missing transitive dependency.","solutions":["Examine the cause exception (getCause()) — CannotResolveClassException names the missing class; ConversionException describes the field and type mismatch.","If a plugin was removed, either reinstall it or manually edit the config XML to remove references to the missing class.","If a class was renamed, add an XStream alias mapping in the plugin's XStream configuration or update the XML to use the new class name.","If the XML is corrupt, restore from a backup (Jenkins keeps config backups in JENKINS_HOME with .bakN suffixes).","For NoClassDefFoundError, ensure the plugin's dependencies are installed at compatible versions."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Validate file is readable and non-empty before deserialization\nif (!file.exists() || file.length() == 0) {\n    throw new IOException(\"Config file missing or empty: \" + file);\n}","typeGuard":null,"tryCatchPattern":"try {\n    Object result = xmlFile.read();\n} catch (IOException e) {\n    Throwable cause = e.getCause();\n    if (cause instanceof CannotResolveClassException) {\n        // A class referenced in XML is not on classpath\n        LOGGER.severe(\"Unknown class in config: \" + cause.getMessage());\n    } else if (cause instanceof ConversionException) {\n        LOGGER.severe(\"Type mismatch in config: \" + cause.getMessage());\n    }\n    // Optionally restore from backup\n}","preventionTips":["Never uninstall plugins without cleaning their config files that reference plugin classes.","Keep config.xml backups (Jenkins does this automatically with .bak suffixes).","Test plugin upgrades in a staging instance before applying to production."],"tags":["xml","serialization","persistence","xstream","config"],"backgroundTag":null,"analyzedSha":"2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc","analyzedAt":"2026-08-14T07:07:15.274Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}