{"record":{"id":"27b505a143a0e524","repo":"pentaho/pentaho-kettle","slug":"trans-log-stepcopiesnotcorrectlydefined","errorCode":null,"errorMessage":"Trans.Log.StepCopiesNotCorrectlyDefined","messagePattern":"Trans\\.Log\\.StepCopiesNotCorrectlyDefined","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/Trans.java","lineNumber":930,"sourceCode":"      }\n\n      List<StepMeta> nextSteps = transMeta.findNextSteps( thisStep );\n      int nrTargets = nextSteps.size();\n\n      for ( int n = 0; n < nrTargets; n++ ) {\n        // What's the next step?\n        StepMeta nextStep = nextSteps.get( n );\n        if ( nextStep.isMapping() ) {\n          continue; // handled and allocated by the mapping step itself.\n        }\n\n        // How many times do we start the source step?\n        int thisCopies = thisStep.getCopies();\n\n        if ( thisCopies < 0 ) {\n          // This can only happen if a variable is used that didn't resolve to a positive integer value\n          //\n          throw new KettleException( BaseMessages.getString( PKG, \"Trans.Log.StepCopiesNotCorrectlyDefined\", thisStep\n            .getName() ) );\n        }\n\n        // How many times do we start the target step?\n        int nextCopies = nextStep.getCopies();\n\n        // Are we re-partitioning?\n        boolean repartitioning;\n        if ( thisStep.isPartitioned() ) {\n          repartitioning = !thisStep.getStepPartitioningMeta().equals( nextStep.getStepPartitioningMeta() );\n        } else {\n          repartitioning = nextStep.isPartitioned();\n        }\n\n        int nrCopies;\n        if ( log.isDetailed() ) {\n          log.logDetailed( BaseMessages.getString( PKG, \"Trans.Log.copiesInfo\", String.valueOf( thisCopies ), String\n            .valueOf( nextCopies ) ) );","sourceCodeStart":912,"sourceCodeEnd":948,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/Trans.java#L912-L948","documentation":"During prepareExecution (Trans constructor phase), row sets are allocated based on step copy counts. If a step's getCopies() returns negative — only possible when the copies value comes from an unresolved or invalid variable that does not resolve to a positive integer — this KettleException is thrown naming the step.","triggerScenarios":"A step configured with ${COPIES}-style variable in 'copies' field that resolves to a non-numeric or negative value, causing getCopies() < 0 during trans.prepareExecution().","commonSituations":"Variable not defined in the runtime environment (kettle.properties / run configuration); typo in variable name so it resolves literally; variable set to 0 or a negative number.","solutions":["Define the copies variable (e.g. in kettle.properties or the run configuration) to a positive integer","Check the step's 'Copies' field for a typo in the variable name","Set a valid default value in the variable expression, e.g. ${NR_OF_COPIES:-1} guards removed — ensure resolution succeeds"],"exampleFix":"// before (step copies field)\n${PARTITION_COUNT}  // undefined at runtime -> resolves invalid\n// after: define PARTITION_COUNT=3 in kettle.properties or set copies to a literal","handlingStrategy":"validation","validationCode":"String copiesExpr = stepMeta.getCopies();\nint copies = Integer.parseInt(transMeta.environmentSubstitute(copiesExpr));\nif (copies < 1) throw new IllegalStateException(\"Variable for copies must resolve to a positive int: \" + copiesExpr);","typeGuard":null,"tryCatchPattern":"try { trans.prepareExecution(); } catch (KettleException e) { log.error(\"Copies misconfigured: \" + e.getMessage()); }","preventionTips":["Define copies variables in kettle.properties or the run configuration","Avoid variables in the Copies field unless guaranteed at runtime","Validate variable resolution with environmentSubstitute before execution"],"tags":["kettle","step-copies","variables"],"backgroundTag":"invalid-env-var-value","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"}