JSch中‘Invalid handle’错误含义及有效性规则咨询

问题背景 #

使用Spring Boot结合Spring Integration与JSch实现文件上传至SFTP服务器，近期上传失败，报错堆栈如下：

Caused by: org.springframework.messaging.MessagingException: Failed to write to './user/2023-04-05_04:00:00_TEST_FILE_FOR_UPLOAD_TO_SFTP_PRODLIKE.csv' while uploading the file; nested exception is org.springframework.core.NestedIOException: failed to write file; nested exception is 9: Invalid handle.
    at org.springframework.integration.file.remote.RemoteFileTemplate.sendFileToRemoteDirectory(RemoteFileTemplate.java:573) ~[spring-integration-file-5.5.12.jar!/:5.5.12]
    at org.springframework.integration.file.remote.RemoteFileTemplate.doSend(RemoteFileTemplate.java:353) ~[spring-integration-file-5.5.12.jar!/:5.5.12]
    ... 166 common frames omitted
 Caused by: org.springframework.core.NestedIOException: failed to write file; nested exception is 9: Invalid handle.
    at org.springframework.integration.sftp.session.SftpSession.write(SftpSession.java:177) ~[spring-integration-sftp-5.5.8.jar!/:5.5.8]
    at org.springframework.integration.file.remote.RemoteFileTemplate.doSend(RemoteFileTemplate.java:582) ~[spring-integration-file-5.5.12.jar!/:5.5.12]
    at org.springframework.integration.file.remote.RemoteFileTemplate.sendFileToRemoteDirectory(RemoteFileTemplate.java:570) ~[spring-integration-file-5.5.12.jar!/:5.5.12]
    ... 167 common frames omitted
 Caused by: com.jcraft.jsch.SftpException: Invalid handle.
    at com.jcraft.jsch.ChannelSftp.throwStatusError(ChannelSftp.java:2873) ~[jsch-0.1.55.jar!/:na]
    at com.jcraft.jsch.ChannelSftp._put(ChannelSftp.java:594) ~[jsch-0.1.55.jar!/:na]
    at com.jcraft.jsch.ChannelSftp.put(ChannelSftp.java:540) ~[jsch-0.1.55.jar!/:na]
    at com.jcraft.jsch.ChannelSftp.put(ChannelSftp.java:492) ~[jsch-0.1.55.jar!/:na]
    at org.springframework.integration.sftp.session.SftpSession.write(SftpSession.java:174) ~[spring-integration-sftp-5.5.8.jar!/:5.5.8]
    ... 169 common frames omitted

已完成排查：

• 跟踪日志确认连接、认证均成功，仅文件写入阶段失败
• 检查服务器磁盘空间充足
• 尝试修改文件名、切换写入目录，问题仍存在
• 搜索未找到JSch下该错误的针对性解决方案，多数结果指向路径问题，但未发现路径异常

核心疑问 #

在此场景下，‘handle’具体指什么？其有效性规则有哪些？

实现代码 #

public class SftpService {
    
    private SftpMessagingGateway gateway;

    @Autowired
    public SftpService(SftpMessagingGateway gateway) {
        this.gateway = gateway;
    }

    public boolean writeStreamToFtp(InputStream data, String filename, String path) {
        if (gateway == null) throw new IllegalStateException("SFTP Gateway is not initialized");

        Message<InputStream> mess = MessageBuilder.withPayload(data)
        .setHeader(FileHeaders.FILENAME, filename)
        .setHeader("path", path)
        .build();
        
        try {
            gateway.send(mess);
            log.info("successful persistence of report to sftp server");
            return true;
        } catch (Exception e) {
            log.error("failed to persist report to sftp server", e);
            return false;
        }
    }

}

问题解答 #

1. SFTP中"handle"的定义 #

在SFTP协议里，handle是服务器返回给客户端的唯一标识符，用来代表一个已打开的文件或目录。客户端请求创建/打开文件时，服务器生成该标识返回，后续对文件的读写、关闭操作都需要通过这个handle指定操作对象。JSch抛出的Invalid handle错误，本质是客户端使用了服务器不认可的handle执行操作。

2. handle的有效性规则 #

• 会话绑定生命周期：handle仅在当前会话、文件/目录处于打开状态时有效。文件关闭、会话断开后，对应handle立即失效，无法再使用。
• 唯一性与时效性：每个handle是当前会话的唯一标识，跨会话不通用；部分SFTP服务器会设置闲置超时，长时间未操作的handle会被主动回收失效。
• 权限匹配要求：handle的有效性依赖于打开文件时的权限。比如以只读权限打开的文件，用该handle执行写入操作会触发错误；若客户端对目标路径无写入权限，服务器可能直接返回无效handle。
• 路径合法性约束：如果打开文件时的路径存在问题（如目录不存在、文件名含服务器禁止的特殊字符），服务器可能返回无效handle，后续写入时就会触发该错误。

3. 针对该场景的排查建议 #

• 检查文件名合法性：你的文件名包含:字符，部分部署在Windows系统的SFTP服务器会将冒号视为非法字符，导致创建文件时服务器返回无效handle，建议移除特殊字符后重试。
• 排查会话复用问题：若SFTP会话被复用，可能存在之前的handle未正确关闭导致的冲突。可配置Spring Integration的SFTP会话工厂，确保每次操作使用独立会话，或显式关闭文件资源。
• 开启协议级日志：在JSch中开启SFTP命令日志（如设置ChannelSftp.setOutputStream(System.out)），查看打开文件时服务器的返回信息，确认是否在打开阶段已出现异常。
• 验证服务器端配置：联系SFTP管理员确认服务器是否有文件创建限制（如大小阈值、目录权限、文件系统配额），部分服务器会返回无效handle而非明确的权限错误。

内容的提问来源于stack exchange，提问作者Marquee