pentaho/pentaho-kettle · error · RuntimeException

The function call copyFile is not valid.

Error message

The function call copyFile is not valid.

What it means

copyFile(source, destination, overwrite) is a scripting function that duplicates a file via KettleVFS. This RuntimeException signals the call itself is malformed rather than an I/O failure: the function requires exactly 3 arguments — source path, destination path, and a boolean overwrite flag — and this message is thrown when that contract (including non-null source) is not met.

Solutions

1. Call copyFile with exactly 3 arguments: copyFile(src, dst, trueOrFalse)
2. Add the missing overwrite boolean (true to replace an existing destination, false otherwise)
3. Ensure the source path variable is non-null and non-undefined before calling
4. If you truly need a 2-arg copy, write a small wrapper function defaulting overwrite to false

Example fix

// before
copyFile(srcPath, dstPath);
// after
copyFile(srcPath, dstPath, true); // explicit overwrite flag

function safeCopy(src, dst, overwrite) {
  if (src == null || dst == null) throw new Error('copyFile needs src and dst');
  if (typeof overwrite !== 'boolean') overwrite = false;
  copyFile(src, dst, overwrite);
}

function canCopy(src, dst, ow) { return typeof src === 'string' && typeof dst === 'string' && typeof ow === 'boolean'; }

try {
  copyFile(src, dst, false);
} catch (e) {
  if (String(e.message).indexOf('copyFile is not valid') >= 0) {
    Logger.logError('copyFile requires 3 args: src, dst, overwrite');
  } else { throw e; }
}

When it happens

Trigger: Calling copyFile with fewer or more than 3 arguments, or with a null/undefined source path — e.g. copyFile(src, dst) omitting the overwrite flag, or a variable holding the source path being undefined.

Common situations: Older examples calling copyFile(src, dst) without the overwrite boolean; the overwrite argument accidentally removed in a refactor; a null path variable produced by an empty upstream field; confusing this with java.nio Files.copy signatures.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• file to move [ + ArgList[0] + ] can not be found!
• Please provide a valid date to the function call date2str.
• Row.EndOfFileReached
• Row.EndOfFileReadingRow
• Row.ErrorWritingRow

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

Appendix: source

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

        } finally {
          if ( fileSource != null ) {
            try {
              fileSource.close();
            } catch ( Exception e ) {
              // Ignore errors
            }
          }
          if ( fileDestination != null ) {
            try {
              fileDestination.close();
            } catch ( Exception e ) {
              // Ignore errors
            }
          }
        }

      } else {
        throw new RuntimeException( "The function call copyFile is not valid." );
      }
    } catch ( Exception e ) {
      throw new RuntimeException( e.toString() );
    }
  }

}

View on GitHub (pinned to f3058517a1)