Textualize/textual · error · WorkerError

Worker must be started before calling this method.

Error message

Worker must be started before calling this method.

What it means

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.

Source

Thrown at src/textual/worker.py:443

        Raises:
            WorkerFailed: If the Worker raised an exception.
            WorkerCancelled: If the Worker was cancelled before it completed.

        Returns:
            The return value of the work.
        """
        try:
            if active_worker.get() is self:
                raise DeadlockError(
                    "Can't call worker.wait from within the worker function!"
                )
        except LookupError:
            # Not in a worker
            pass

        if self.state == WorkerState.PENDING:
            raise WorkerError("Worker must be started before calling this method.")
        if self._task is not None:
            try:
                await self._task
            except asyncio.CancelledError as error:
                self.state = WorkerState.CANCELLED
                self._error = error
        if self.state == WorkerState.ERROR:
            assert self._error is not None
            raise WorkerFailed(self._error)
        elif self.state == WorkerState.CANCELLED:
            raise WorkerCancelled("Worker was cancelled, and did not complete.")
        return cast("ResultType", self._result)

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Start the worker first: `worker.start()` (or let run_worker start it) before awaiting.
2. Prefer `worker = self.run_worker(fn)` then `await worker.wait()` — run_worker starts by default.
3. Check `worker.state != WorkerState.PENDING` before waiting.

Example fix

# before
worker = self.run_worker(fn, start=False)
await worker.wait()
# after
worker = self.run_worker(fn)
await worker.wait()

from textual.worker import WorkerState
if worker.state != WorkerState.PENDING:
    await worker.wait()

from textual.worker import WorkerError
try:
    await worker.wait()
except WorkerError:
    worker.start()

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Can not create a worker from a non-async function unless `th
• Request to run a non-async function as an async worker
• Unsupported attempt to run an async worker
• Can't call worker.wait from within the worker function!
• Worker was cancelled, and did not complete.

AI-assisted analysis of Textualize/textual@06dbeef4bb (2026-08-27). Data as JSON: /api/errors/77098e925ab15bcd. Report an issue: GitHub.