{"record":{"id":"8633407a1e12815c","repo":"pentaho/pentaho-kettle","slug":"unknown-permissions-error","errorCode":null,"errorMessage":"Unknown permissions error","messagePattern":"Unknown permissions error","errorType":"exception","errorClass":"KettleJobException","httpStatus":null,"severity":"warning","filePath":"engine/src/main/java/org/pentaho/di/job/entries/sftp/SFTPClient.java","lineNumber":398,"sourceCode":"   * Rename the file.\n   */\n  public void renameFile( String sourcefilename, String destinationfilename ) throws KettleJobException {\n    try {\n      channel.rename( sourcefilename, destinationfilename );\n    } catch ( SftpException e ) {\n      throw new KettleJobException( e );\n    }\n  }\n\n  public FileType getFileType( String filename ) throws KettleJobException {\n    try {\n      SftpATTRS attrs = channel.stat( filename );\n      if ( attrs == null ) {\n        return FileType.IMAGINARY;\n      }\n\n      if ( ( attrs.getFlags() & SftpATTRS.SSH_FILEXFER_ATTR_PERMISSIONS ) == 0 ) {\n        throw new KettleJobException( \"Unknown permissions error\" );\n      }\n\n      if ( attrs.isDir() ) {\n        return FileType.FOLDER;\n      } else {\n        return FileType.FILE;\n      }\n    } catch ( Exception e ) {\n      throw new KettleJobException( e );\n    }\n  }\n\n  public boolean folderExists( String foldername ) {\n    boolean retval = false;\n    try {\n      SftpATTRS attrs = channel.stat( foldername );\n      if ( attrs == null ) {\n        return false;","sourceCodeStart":380,"sourceCodeEnd":416,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/job/entries/sftp/SFTPClient.java#L380-L416","documentation":"SFTPClient.getFileType() stats the remote file and inspects SftpATTRS flags. If the server's attribute reply lacks the SSH_FILEXFER_ATTR_PERMISSIONS flag, the client cannot classify the entry and throws KettleJobException(\"Unknown permissions error\"). It signals an incomplete SFTP ATTR structure rather than a permissions denial.","triggerScenarios":"channel.stat(filename) returns attrs whose getFlags() has the PERMISSIONS bit cleared — some SFTP servers/sFTP proxies omit permissions in their stat replies.","commonSituations":"Non-standard or embedded SFTP servers (appliances, cloud storage SFTP gateways) that return minimal attrs; calling getFileType() on a server after a chroot config change; buggy SFTP middleware. RFC-compliant OpenSSH servers normally include the flag.","solutions":["Avoid getFileType() on such servers; use channel.stat + attrs.isDir() directly without requiring the permissions flag, or a different existence check (e.g. try cd() or ls())","Check the server implementation; upgrade or reconfigure it to return permissions attrs","Catch the exception and fall back to a NAME/IMAGINARY classification","Test with sftp client/verbose logging to inspect returned ATTR flags"],"exampleFix":"// before\nFileType ft = sftpClient.getFileType(remoteFile);\n// after\nFileType ft;\ntry {\n  ft = sftpClient.getFileType(remoteFile);\n} catch (KettleJobException e) {\n  // server omitted permissions attrs; treat by other means\n  ft = sftpClient.fileExists(remoteFile) ? FileType.FILE : FileType.IMAGINARY;\n}","handlingStrategy":"try-catch","validationCode":"// pre-check attributes yourself and tolerate missing permission flags\nSftpATTRS attrs = channelStat(filename);\nboolean isDir = attrs != null && attrs.isDir(); // works without PERMISSIONS flag","typeGuard":null,"tryCatchPattern":"try {\n  ft = sftpClient.getFileType(filename);\n} catch (KettleJobException e) {\n  if (e.getMessage().contains(\"Unknown permissions error\")) {\n    ft = sftpClient.fileExists(filename) ? FileType.FILE : FileType.IMAGINARY;\n  } else {\n    throw e;\n  }\n}","preventionTips":["Prefer attrs.isDir()-based checks over requiring permission flags","Test against the actual SFTP server product — some gateways omit PERMISSIONS attrs","Keep the server updated (OpenSSH and similar include the flag per RFC)","Wrap server-compat-sensitive helpers in fallback logic"],"tags":["sftp","sftp-attrs","permissions","server-compatibility"],"backgroundTag":"unexpected-response-shape","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}