{"record":{"id":"034cb70229699a2e","repo":"jenkinsci/jenkins","slug":"remote-file-operation-failed","errorCode":null,"errorMessage":"remote file operation failed","messagePattern":"remote file operation failed","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/hudson/FilePath.java","lineNumber":1300,"sourceCode":"        protected void after() {}\n    }\n\n\n    /**\n     * Executes some program on the machine that this {@link FilePath} exists,\n     * so that one can perform local file operations.\n     */\n    public <T> Future<T> actAsync(final FileCallable<T> callable) throws IOException, InterruptedException {\n        try {\n            DelegatingCallable<T, IOException> wrapper = new FileCallableWrapper<>(callable, this);\n            for (FileCallableWrapperFactory factory : ExtensionList.lookup(FileCallableWrapperFactory.class)) {\n                wrapper = factory.wrap(wrapper);\n            }\n            return (channel != null ? channel : localChannel)\n                .callAsync(wrapper);\n        } catch (IOException e) {\n            // wrap it into a new IOException so that we get the caller's stack trace as well.\n            throw new IOException(\"remote file operation failed\", e);\n        }\n    }\n\n    /**\n     * Executes some program on the machine that this {@link FilePath} exists,\n     * so that one can perform local file operations.\n     */\n    public <V, E extends Throwable> V act(Callable<V, E> callable) throws IOException, InterruptedException, E {\n        if (channel != null) {\n            // run this on a remote system\n            return channel.call(callable);\n        } else {\n            // the file is on the local machine\n            return callable.call();\n        }\n    }\n\n    /**","sourceCodeStart":1282,"sourceCodeEnd":1318,"githubUrl":"https://github.com/jenkinsci/jenkins/blob/2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc/core/src/main/java/hudson/FilePath.java#L1282-L1318","documentation":"Thrown by FilePath.actAsync when wrapping the FileCallable and dispatching it over the channel fails with IOException. The fresh IOException preserves the caller's stack trace (remote exceptions lose the calling frame), with the original as cause. This wraps channel-level failures, not the inner callable's business exceptions.","triggerScenarios":"Remoting channel is closed/disconnected; callable or its arguments are not serializable; FileCallableWrapperFactory wrapping throws; channel.callAsync raises IOException before dispatch.","commonSituations":"Agent went offline mid-operation; passing a non-Serializable lambda/closure to actAsync; channel degraded after a restart; custom FileCallableWrapperFactory throws.","solutions":["Ensure the agent is online and the channel is healthy before the call.","Make the FileCallable and all its fields Serializable (use MasterToSlaveFileCallable).","Inspect the cause for NotSerializableException and annotate/strip offending fields.","Check FileCallableWrapperFactory extensions for failures."],"exampleFix":"// before\nfp.actAsync(in -> doWork(in)); // lambda may not be serializable\n// after\nfp.actAsync(new MasterToSlaveFileCallable<Result>() {\n    private static final long serialVersionUID = 1L;\n    public Result invoke(File f, VirtualChannel ch) { return doWork(f); }\n});","handlingStrategy":"validation","validationCode":"if (callable instanceof Serializable && channel != null && channel.isClosingOrClosed()) {\n    // channel unhealthy — defer or fail fast before actAsync\n}","typeGuard":"static boolean isRemotable(Object c) { return c instanceof Serializable; }","tryCatchPattern":"try {\n    Future<T> f = fp.actAsync(callable);\n} catch (IOException e) {\n    // 'remote file operation failed' — check cause for channel/serialization issues\n    if (e.getCause() instanceof NotSerializableException) { /* make callable serializable */ }\n}","preventionTips":["Always use MasterToSlaveFileCallable (serializable) for act/actAsync.","Check agent/channel health before dispatching remote file ops.","Audit FileCallableWrapperFactory extensions for failures."],"tags":["remoting","serialization","agent"],"backgroundTag":null,"analyzedSha":"2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc","analyzedAt":"2026-08-14T07:07:15.274Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}