{"record":{"id":"9fe9b26a5627cf0c","repo":"jenkinsci/jenkins","slug":"failed-to-install-archive-to-remote","errorCode":null,"errorMessage":"Failed to install ${archive} to ${remote}","messagePattern":"Failed to install (.+?) to (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/hudson/FilePath.java","lineNumber":1073,"sourceCode":"            InputStream in = archive.getProtocol().startsWith(\"http\") ? ProxyConfiguration.getInputStream(archive) : con.getInputStream();\n            CountingInputStream cis = new CountingInputStream(in);\n            try {\n                if (archive.toExternalForm().endsWith(\".zip\"))\n                    unzipFrom(cis);\n                else\n                    untarFrom(cis, TarCompression.GZIP);\n            } catch (IOException e) {\n                throw new IOException(String.format(\"Failed to unpack %s (%d bytes read of total %d)\",\n                        archive, cis.getByteCount(), con.getContentLength()), e);\n            }\n            if (resultEtag != null && !equalETags(etag, resultEtag)) {\n                /* Store the ETag value in the timestamp file for later use */\n                timestamp.write(resultEtag, \"UTF-8\");\n            }\n            timestamp.touch(sourceTimestamp);\n            return true;\n        } catch (IOException e) {\n            throw new IOException(\"Failed to install \" + archive + \" to \" + remote, e);\n        }\n    }\n\n    /* Return true if etag1 equals etag2 as defined by the etag specification\n       https://httpwg.org/specs/rfc9110.html#field.etag\n     */\n    private boolean equalETags(String etag1, String etag2) {\n        if (etag1 == null || etag2 == null) {\n            return false;\n        }\n        if (etag1.equals(etag2)) {\n            return true;\n        }\n        /* Weak tags are identified by leading characters \"W/\" as a marker */\n        /* Weak tag marker must not be considered in tag comparison.\n           This implements the weak comparison in the specification at\n           https://httpwg.org/specs/rfc9110.html#field.etag */\n        String opaqueTag1 = etag1.startsWith(\"W/\") ? etag1.substring(2) : etag1;","sourceCodeStart":1055,"sourceCodeEnd":1091,"githubUrl":"https://github.com/jenkinsci/jenkins/blob/2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc/core/src/main/java/hudson/FilePath.java#L1055-L1091","documentation":"Outer catch in FilePath.install(...) wrapping any IOException raised during the whole install operation (download, mkdirs, unpack, etag/timestamp write). It re-throws a fresh IOException with the caller's context (archive URL and remote path) and the original as cause. This is the top-level install failure surfaced to callers.","triggerScenarios":"Any IOException from connect/getInputStream, mkdirs, unzipFrom/untarFrom, the inner 'Failed to unpack', or timestamp.touch; the agent-side Unpack retry already failed and fell through to controller-side unpack which then failed.","commonSituations":"Target directory not writable; remote agent path invalid or disconnected; archive URL returns 4xx/5xx; nested cause is one of the more specific unpack/mkdirs errors.","solutions":["Read the nested cause to find the specific failure (unpack, mkdirs, network).","Verify the remote path exists and is writable, and the agent channel is up.","Confirm the archive URL is reachable and returns the expected content.","Fix the root cause identified in the cause chain, then retry install."],"exampleFix":"null","handlingStrategy":"try-catch","validationCode":"null","typeGuard":"null","tryCatchPattern":"try {\n    fp.install(archive, listener);\n} catch (IOException e) {\n    // 'Failed to install' — inspect e.getCause() for the specific failure\n    LOGGER.log(Level.SEVERE, \"install failed\", e.getCause());\n}","preventionTips":["Pre-check the remote path writability and agent connectivity before install.","Validate the source URL returns 200 and the right content type.","Free disk space on the target volume before large installs."],"tags":["install","filepath","wrapper"],"backgroundTag":null,"analyzedSha":"2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc","analyzedAt":"2026-08-14T07:07:15.274Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}