pentaho/pentaho-kettle · error · RuntimeException

The function call copyFile throw an error :

Error message

The function call copyFile throw an error :

What it means

copyFile() catches IOException from path resolution or FileUtil.copyContent and rethrows as 'The function call copyFile throw an error : ' + e.toString(). Unlike some sibling functions, the underlying IOException message is preserved, pointing at the real IO failure during resolve or copy.

Solutions

  1. Read the appended e.toString() in the message to identify the real cause and fix that specific IO problem.
  2. Ensure the destination directory exists (createFolder first) and is writable by the process user.
  3. Validate both source and destination as proper VFS URIs (forward slashes, valid scheme).
  4. Check free disk space and quota for large files.
  5. For remote destinations, verify connectivity/credentials before running the copy.

Example fix

// before
copyFile('file:///data/in.csv', 'file:///data/archive/in.csv', true); // archive dir missing
// after
if (!fileExists('file:///data/archive')) { createFolder('file:///data/archive'); }
copyFile('file:///data/in.csv', 'file:///data/archive/in.csv', true);
Defensive patterns

Strategy: try-catch

Validate before calling

if (!fileExists(src)) throw new Error('missing source');
if (!fileExists(destFolder)) createFolder(destFolder);

Type guard

function isVfsUri(p) { return typeof p === 'string' && (/^[a-z]+:\/\//.test(p) || p.startsWith('/')); }

Try / catch

try { copyFile(src, dest, true); } catch (e) { // e.toString() already carries the IOException; log and rethrow or fall back
  throw e; }

Prevention

When it happens

Trigger: Calling copyFile(src, dest, overwrite) where an IOException occurs: malformed source/destination URI, destination unwritable, target directory missing, network filesystem error, or disk full during copyContent.

Common situations: Destination directory does not exist; no write permission on the destination; sftp/webdav destinations unreachable; malformed VFS URIs (backslashes, bad scheme); insufficient disk space on large copies.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/script/ScriptAddedFunctions.java:2056

            // Source file exists...
            if ( fileSource.getType() == FileType.FILE ) {
              // Great..source is a file ...
              boolean overwrite = false;
              if ( !ArgList[1].equals( null ) ) {
                overwrite = (Boolean) ArgList[2];
              }
              boolean destinationExists = fileDestination.exists();
              // Let's copy the file...
              if ( ( destinationExists && overwrite ) || !destinationExists ) {
                FileUtil.copyContent( fileSource, fileDestination );
              }

            }
          } else {
            throw new RuntimeException( "file to copy [" + ArgList[0] + "] can not be found!" );
          }
        } catch ( IOException e ) {
          throw new RuntimeException( "The function call copyFile throw an error : " + e.toString() );
        } finally {
          if ( fileSource != null ) {
            try {
              fileSource.close();
            } catch ( Exception e ) {
              // Ignore errors
            }
          }
          if ( fileDestination != null ) {
            try {
              fileDestination.close();
            } catch ( Exception e ) {
              // Ignore errors
            }
          }
        }

      } else {

View on GitHub (pinned to f3058517a1)