{"record":{"id":"214ec7552c25a6e0","repo":"microsoft/semantic-kernel","slug":"the-task-ledger-is-not-initialized-planning-needs","errorCode":null,"errorMessage":"The task ledger is not initialized. Planning needs to happen first.","messagePattern":"The task ledger is not initialized\\. Planning needs to happen first\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/orchestration/magentic.py","lineNumber":332,"sourceCode":"            self.prompt_execution_settings,\n        )\n        assert plan is not None  # nosec B101\n\n        self.task_ledger = _TaskLedger(facts=facts, plan=plan)\n        return await self._render_task_ledger(magentic_context)\n\n    @override\n    async def replan(self, magentic_context: MagenticContext) -> ChatMessageContent:\n        \"\"\"Replan the task.\n\n        Args:\n            magentic_context (MagenticContext): The context for the Magentic manager.\n\n        Returns:\n            ChatMessageContent: The updated task ledger.\n        \"\"\"\n        if self.task_ledger is None:\n            raise RuntimeError(\"The task ledger is not initialized. Planning needs to happen first.\")\n\n        # 1. Update the facts\n        prompt_template = KernelPromptTemplate(\n            prompt_template_config=PromptTemplateConfig(template=self.task_ledger_facts_update_prompt)\n        )\n        magentic_context.chat_history.add_message(\n            ChatMessageContent(\n                role=AuthorRole.USER,\n                content=await prompt_template.render(\n                    Kernel(),\n                    KernelArguments(task=magentic_context.task.content, old_facts=self.task_ledger.facts.content),\n                ),\n            )\n        )\n        facts = await self.chat_completion_service.get_chat_message_content(\n            magentic_context.chat_history,\n            self.prompt_execution_settings,\n        )","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/orchestration/magentic.py#L314-L350","documentation":"replan() reads self.task_ledger to update facts and the plan. That ledger is only created inside plan(), so calling replan on a manager that has never planned leaves task_ledger as None and the method cannot proceed. The manager enforces the plan-then-replan lifecycle.","triggerScenarios":"Calling `await manager.replan(context)` on a StandardMagenticManager instance whose `plan()` was never invoked (task_ledger is still its default None). Common when driving the manager manually instead of through MagenticOrchestration.","commonSituations":"Subclassing or scripting the manager directly and skipping the initial planning step. Reusing a manager instance for a new task without re-planning. Test code that exercises replan in isolation.","solutions":["Call `await manager.plan(context)` first to initialize the task ledger before any replan.","Drive the manager through MagenticOrchestration.invoke(), which calls plan/replan in the correct order automatically.","If reusing the instance for a new task, reset by constructing a fresh StandardMagenticManager or re-running plan()."],"exampleFix":"// before\nmanager = StandardMagenticManager(service)\nawait manager.replan(context)  # raises: ledger is None\n\n// after\nmanager = StandardMagenticManager(service)\nawait manager.plan(context)      # initializes task ledger\nawait manager.replan(context)    # ok","handlingStrategy":"validation","validationCode":"# Ensure plan ran before replan\nif getattr(manager, \"task_ledger\", None) is None:\n    await manager.plan(context)  # initialize ledger\nawait manager.replan(context)","typeGuard":"def manager_has_plan(mgr) -> bool:\n    return getattr(mgr, \"task_ledger\", None) is not None","tryCatchPattern":null,"preventionTips":["Always call plan() before replan() on the same manager instance.","Prefer MagenticOrchestration.invoke() which manages the plan/replan lifecycle.","Construct a fresh StandardMagenticManager per independent task."],"tags":["semantic-kernel","magentic","lifecycle","state","precondition"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}