{"record":{"id":"77098e925ab15bcd","repo":"Textualize/textual","slug":"worker-must-be-started-before-calling-this-method","errorCode":null,"errorMessage":"Worker must be started before calling this method.","messagePattern":"Worker must be started before calling this method\\.","errorType":"exception","errorClass":"WorkerError","httpStatus":null,"severity":"error","filePath":"src/textual/worker.py","lineNumber":443,"sourceCode":"\n        Raises:\n            WorkerFailed: If the Worker raised an exception.\n            WorkerCancelled: If the Worker was cancelled before it completed.\n\n        Returns:\n            The return value of the work.\n        \"\"\"\n        try:\n            if active_worker.get() is self:\n                raise DeadlockError(\n                    \"Can't call worker.wait from within the worker function!\"\n                )\n        except LookupError:\n            # Not in a worker\n            pass\n\n        if self.state == WorkerState.PENDING:\n            raise WorkerError(\"Worker must be started before calling this method.\")\n        if self._task is not None:\n            try:\n                await self._task\n            except asyncio.CancelledError as error:\n                self.state = WorkerState.CANCELLED\n                self._error = error\n        if self.state == WorkerState.ERROR:\n            assert self._error is not None\n            raise WorkerFailed(self._error)\n        elif self.state == WorkerState.CANCELLED:\n            raise WorkerCancelled(\"Worker was cancelled, and did not complete.\")\n        return cast(\"ResultType\", self._result)\n","sourceCodeStart":425,"sourceCodeEnd":456,"githubUrl":"https://github.com/Textualize/textual/blob/06dbeef4bb70fb718236aa418ed658ef4667a126/src/textual/worker.py#L425-L456","documentation":"WorkerError from Worker.wait(): wait() awaits the worker's asyncio task, which only exists after the worker has been started. Calling wait() while state is PENDING (created but run_worker never actually launched it) is invalid.","triggerScenarios":"Holding a Worker object returned by run_worker(..., start=False) (or constructed directly) and calling `await worker.wait()` before `worker.start()`/run has been invoked.","commonSituations":"Manually managing worker lifecycle; calling wait() in on_mount before the app is running and the worker task was scheduled; test code that creates Worker instances directly.","solutions":["Start the worker first: `worker.start()` (or let run_worker start it) before awaiting.","Prefer `worker = self.run_worker(fn)` then `await worker.wait()` — run_worker starts by default.","Check `worker.state != WorkerState.PENDING` before waiting."],"exampleFix":"# before\nworker = self.run_worker(fn, start=False)\nawait worker.wait()\n# after\nworker = self.run_worker(fn)\nawait worker.wait()","handlingStrategy":"validation","validationCode":"from textual.worker import WorkerState\nif worker.state != WorkerState.PENDING:\n    await worker.wait()","typeGuard":null,"tryCatchPattern":"from textual.worker import WorkerError\ntry:\n    await worker.wait()\nexcept WorkerError:\n    worker.start()","preventionTips":["Let run_worker auto-start workers","If using start=False, always call start() before wait()"],"tags":["worker","lifecycle","async","textual"],"backgroundTag":"worker-not-started","analyzedSha":"06dbeef4bb70fb718236aa418ed658ef4667a126","analyzedAt":"2026-08-27T02:36:57.214Z","schemaVersion":2},"datasetVersion":"2026-08-27T03:17:27.898Z"}