{"record":{"id":"b33823219883ba14","repo":"pentaho/pentaho-kettle","slug":"filelocked-error-filenamefieldmissing","errorCode":"FileLocked.Error.FilenameFieldMissing","errorMessage":"FileLocked.Error.FilenameFieldMissing","messagePattern":"FileLocked\\.Error\\.FilenameFieldMissing","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/filelocked/FileLocked.java","lineNumber":76,"sourceCode":"      setOutputDone();\n      return false;\n    }\n\n    boolean FileLocked = false;\n\n    if ( first ) {\n      first = false;\n      // get the RowMeta\n      data.previousRowMeta = getInputRowMeta().clone();\n      data.NrPrevFields = data.previousRowMeta.size();\n      data.outputRowMeta = data.previousRowMeta;\n      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,\n        metaStore );\n\n      // Check is filename field is provided\n      if ( Utils.isEmpty( meta.getDynamicFilenameField() ) ) {\n        logError( BaseMessages.getString( PKG, \"FileLocked.Error.FilenameFieldMissing\" ) );\n        throw new KettleException( BaseMessages.getString( PKG, \"FileLocked.Error.FilenameFieldMissing\" ) );\n      }\n\n      // cache the position of the field\n      if ( data.indexOfFileename < 0 ) {\n        data.indexOfFileename = data.previousRowMeta.indexOfValue( meta.getDynamicFilenameField() );\n        if ( data.indexOfFileename < 0 ) {\n          // The field is unreachable !\n          logError( BaseMessages.getString( PKG, \"FileLocked.Exception.CouldnotFindField\" )\n            + \"[\" + meta.getDynamicFilenameField() + \"]\" );\n          throw new KettleException( BaseMessages.getString( PKG, \"FileLocked.Exception.CouldnotFindField\", meta\n            .getDynamicFilenameField() ) );\n        }\n      }\n    } // End If first\n\n    try {\n      // get filename\n      String filename = data.previousRowMeta.getString( r, data.indexOfFileename );","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/filelocked/FileLocked.java#L58-L94","documentation":"The FileLocked step checks if a file is locked, and the name of the file can either be static or taken from an incoming row field. This error is thrown in processRow when the step's meta configuration has no 'dynamic filename field' set, so the step does not know which incoming field contains the file path to test.","triggerScenarios":"processRow() runs and Utils.isEmpty(meta.getDynamicFilenameField()) is true, i.e. the 'filename field' textbox in the FileLocked step dialog was left empty when the transformation was saved.","commonSituations":"Transformation exported/copied between environments loses step settings; user created the step but never opened the dialog to configure it; a repository or XML round-trip dropped the 'filenamefield' attribute (e.g. older file saved by a version without that option).","solutions":["Open the FileLocked step dialog and set the 'filename field' to an incoming String field containing the file path.","If the file name is fixed, do not use the dynamic field option - configure the step accordingly or use a 'Get File Names'/'Text File Input' approach feeding the field.","Inspect the transformation XML/repository entry to confirm the <filenamefield> tag has a non-empty value before running."],"exampleFix":"// before (transformation XML)\n<filenamefield></filenamefield>\n// after\n<filenamefield>filename</filenamefield>","handlingStrategy":"validation","validationCode":"// Before running the transformation, verify the step config:\nFileLockedMeta meta = (FileLockedMeta) transMeta.findStep(\"FileLocked\").getStepMeta();\nif (meta.getDynamicFilenameField() == null || meta.getDynamicFilenameField().isEmpty()) {\n  throw new IllegalStateException(\"FileLocked step has no filename field configured\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set the filename field via the step dialog's 'Get fields' button, never by hand-editing XML.","Validate transformations programmatically (transMeta.validate / step meta check) before execution.","Diff transformation XML across environments after export/import."],"tags":["kettle","step-configuration","missing-field"],"backgroundTag":"missing-required-config-field","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"}