What causes "Unknown permissions error" in pentaho/pentaho-kettle?

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())

pentaho/pentaho-kettle · warning · KettleJobException

Unknown permissions error

Error message

Unknown permissions error

What it means

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.

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

Example fix

// before
FileType ft = sftpClient.getFileType(remoteFile);
// after
FileType ft;
try {
  ft = sftpClient.getFileType(remoteFile);
} catch (KettleJobException e) {
  // server omitted permissions attrs; treat by other means
  ft = sftpClient.fileExists(remoteFile) ? FileType.FILE : FileType.IMAGINARY;
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check attributes yourself and tolerate missing permission flags
SftpATTRS attrs = channelStat(filename);
boolean isDir = attrs != null && attrs.isDir(); // works without PERMISSIONS flag

Try / catch

try {
  ft = sftpClient.getFileType(filename);
} catch (KettleJobException e) {
  if (e.getMessage().contains("Unknown permissions error")) {
    ft = sftpClient.fileExists(filename) ? FileType.FILE : FileType.IMAGINARY;
  } else {
    throw e;
  }
}

Prevention

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

When it happens

Trigger: channel.stat(filename) returns attrs whose getFlags() has the PERMISSIONS bit cleared — some SFTP servers/sFTP proxies omit permissions in their stat replies.

Common situations: 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.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/8633407a1e12815c. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/job/entries/sftp/SFTPClient.java:398

   * Rename the file.
   */
  public void renameFile( String sourcefilename, String destinationfilename ) throws KettleJobException {
    try {
      channel.rename( sourcefilename, destinationfilename );
    } catch ( SftpException e ) {
      throw new KettleJobException( e );
    }
  }

  public FileType getFileType( String filename ) throws KettleJobException {
    try {
      SftpATTRS attrs = channel.stat( filename );
      if ( attrs == null ) {
        return FileType.IMAGINARY;
      }

      if ( ( attrs.getFlags() & SftpATTRS.SSH_FILEXFER_ATTR_PERMISSIONS ) == 0 ) {
        throw new KettleJobException( "Unknown permissions error" );
      }

      if ( attrs.isDir() ) {
        return FileType.FOLDER;
      } else {
        return FileType.FILE;
      }
    } catch ( Exception e ) {
      throw new KettleJobException( e );
    }
  }

  public boolean folderExists( String foldername ) {
    boolean retval = false;
    try {
      SftpATTRS attrs = channel.stat( foldername );
      if ( attrs == null ) {
        return false;

View on GitHub (pinned to f3058517a1)