{"record":{"id":"34401c00d6fd758b","repo":"apache/flink","slug":"this-stub-is-not-part-of-an-iteration-step-functio","errorCode":null,"errorMessage":"This stub is not part of an iteration step function.","messagePattern":"This stub is not part of an iteration step function\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/common/functions/AbstractRichFunction.java","lineNumber":62,"sourceCode":"    }\n\n    @Override\n    public RuntimeContext getRuntimeContext() {\n        if (this.runtimeContext != null) {\n            return this.runtimeContext;\n        } else {\n            throw new IllegalStateException(\"The runtime context has not been initialized.\");\n        }\n    }\n\n    @Override\n    public IterationRuntimeContext getIterationRuntimeContext() {\n        if (this.runtimeContext == null) {\n            throw new IllegalStateException(\"The runtime context has not been initialized.\");\n        } else if (this.runtimeContext instanceof IterationRuntimeContext) {\n            return (IterationRuntimeContext) this.runtimeContext;\n        } else {\n            throw new IllegalStateException(\"This stub is not part of an iteration step function.\");\n        }\n    }\n\n    // --------------------------------------------------------------------------------------------\n    //  Default life cycle methods\n    // --------------------------------------------------------------------------------------------\n\n    @Override\n    public void open(OpenContext openContext) throws Exception {}\n\n    @Override\n    public void close() throws Exception {}\n}\n","sourceCodeStart":44,"sourceCodeEnd":76,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/functions/AbstractRichFunction.java#L44-L76","documentation":"Thrown by AbstractRichFunction.getIterationRuntimeContext() when a RuntimeContext exists but is not an IterationRuntimeContext. This means the function is executing in a normal (non-iteration) streaming or batch context, but the code attempted to access iteration-specific features like iteration aggregators or brokered state.","triggerScenarios":"A RichFunction used inside a regular DataStream (no iterate() call) invokes getIterationRuntimeContext(). The runtime set a StreamingRuntimeContext or a plain RuntimeContext, neither of which implements IterationRuntimeContext.","commonSituations":"A step function from a Flink iteration is accidentally reused in a non-iteration pipeline. Copying code from an iteration-based job into a regular streaming job without removing iteration-specific calls. Using the legacy delta iteration API incorrectly.","solutions":["Remove the getIterationRuntimeContext() call if the function is not used inside an iterate() / closeWith() block.","If the function is meant for an iteration, ensure it is wired into the iteration step via DataSet.iterate() / DataStream.iterate() and that the job graph actually builds an iteration.","Use instanceof or try-catch to make the iteration-context access optional if the function is shared between iteration and non-iteration pipelines."],"exampleFix":"// before\nIterationRuntimeContext ctx = getIterationRuntimeContext();\n// throws if not in iteration\n\n// after — guard with type check\nif (getRuntimeContext() instanceof IterationRuntimeContext) {\n    IterationRuntimeContext ctx = getIterationRuntimeContext();\n    // iteration-specific logic\n} else {\n    // fallback for non-iteration usage\n}","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"if (getRuntimeContext() instanceof IterationRuntimeContext) {\n    IterationRuntimeContext ctx = getIterationRuntimeContext();\n    // iteration-specific logic\n}","tryCatchPattern":null,"preventionTips":["Guard iteration context access with an instanceof check on getRuntimeContext().","Do not reuse iteration step functions in non-iteration pipelines without conditional access.","Document which functions require iteration context so they are not misused in regular streams."],"tags":["rich-function","iteration","runtime-context","misuse"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}