{"record":{"id":"564fbe8e2ea78459","repo":"jenkinsci/jenkins","slug":"jenkins-war-location-is-not-known","errorCode":null,"errorMessage":"jenkins.war location is not known.","messagePattern":"jenkins\\.war location is not known\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/hudson/lifecycle/Lifecycle.java","lineNumber":169,"sourceCode":"        String war = SystemProperties.getString(\"executable-war\");\n        if (war != null && new File(war).exists())\n            return new File(war);\n        return null;\n    }\n\n    /**\n     * Replaces jenkins.war by the given file.\n     *\n     * <p>\n     * On some system, most notably Windows, a file being in use cannot be changed,\n     * so rewriting {@code jenkins.war} requires some special trick. Override this method\n     * to do so.\n     */\n    public void rewriteHudsonWar(File by) throws IOException {\n        File dest = getHudsonWar();\n        // this should be impossible given the canRewriteHudsonWar method,\n        // but let's be defensive\n        if (dest == null)  throw new IOException(\"jenkins.war location is not known.\");\n\n        // backing up the old jenkins.war before it gets lost due to upgrading\n        // (newly downloaded jenkins.war and 'backup' (jenkins.war.tmp) are the same files\n        // unless we are trying to rewrite jenkins.war by a backup itself\n        File bak = new File(dest.getPath() + \".bak\");\n        if (!by.equals(bak))\n            FileUtils.copyFile(dest, bak);\n\n        FileUtils.copyFile(by, dest);\n        // we don't want to keep backup if we are downgrading\n        if (by.equals(bak)) {\n            Files.deleteIfExists(Util.fileToPath(bak));\n        }\n    }\n\n    /**\n     * Can {@link #rewriteHudsonWar(File)} work?\n     */","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/jenkinsci/jenkins/blob/2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc/core/src/main/java/hudson/lifecycle/Lifecycle.java#L151-L187","documentation":"Thrown by Lifecycle.rewriteHudsonWar(File) when getHudsonWar() returns null. This base implementation is used to overwrite jenkins.war during an in-place upgrade. A null war path means Jenkins could not determine where its own war file lives. The code comment notes this should be impossible if canRewriteHudsonWar() was honored, hence it is a defensive guard.","triggerScenarios":"An upgrade or downgrade path calls rewriteHudsonWar(by); getHudsonWar() returns null because the war location was never set (e.g. launched from an exploded classpath or a custom main that does not set the war file).","commonSituations":"Running Jenkins from an IDE or exploded webapp where there is no jenkins.war on disk; deploying under a servlet container (Tomcat) where the war identity differs; a custom launcher that does not populate the war location.","solutions":["Run Jenkins from the actual jenkins.war file so the war location is resolvable","If using a servlet container, perform upgrades by redeploying the war via the container, not via Jenkins' restart API","Check that the war location system property / launch argument is set correctly","Avoid calling the in-place upgrade API in environments without a physical war file"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"Lifecycle lc = Lifecycle.get();\nif (lc.getHudsonWar() == null) {\n    throw new IllegalStateException(\"No jenkins.war location; in-place upgrade is not available in this mode\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Lifecycle.get().rewriteHudsonWar(newWar);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"jenkins.war location is not known\")) {\n        // cannot do in-place upgrade here; redeploy externally\n    }\n    throw e;\n}","preventionTips":["Run Jenkins from the physical jenkins.war so getHudsonWar() resolves","For servlet-container deployments, use the container's redeploy mechanism instead","Check canRewriteHudsonWar() semantics before calling rewriteHudsonWar"],"tags":["lifecycle","war-location","upgrade","unsupported-operation"],"backgroundTag":null,"analyzedSha":"2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc","analyzedAt":"2026-08-14T07:07:15.274Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}