{"record":{"id":"7631cab180eaf1d8","repo":"mastra-ai/mastra","slug":"backgroundtaskmanager-is-shutting-down-cannot-res-7631ca","errorCode":null,"errorMessage":"BackgroundTaskManager is shutting down, cannot restart tasks","messagePattern":"BackgroundTaskManager is shutting down, cannot restart tasks","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/background-tasks/manager.ts","lineNumber":466,"sourceCode":"    await this.pubsub.publish(TOPIC_DISPATCH, {\n      type: 'task.resume',\n      data: { taskId, resumeData },\n      runId: taskId,\n    });\n\n    return task;\n  }\n\n  /**\n   * Restarts a previously running task. The tool executor is re-registered via\n   * `registerTaskContext(taskId, ...)` because the original\n   * registration is gone (e.g. process restart) — the manager doesn't\n   * rehydrate executor closures from storage.\n   *\n   */\n  async restart(taskId: string, context?: TaskContext): Promise<BackgroundTask> {\n    if (this.shuttingDown) {\n      throw new Error('BackgroundTaskManager is shutting down, cannot restart tasks');\n    }\n    if (!this.#mastra) {\n      throw new Error('Mastra is not registered with this manager');\n    }\n\n    if (this.initPromise) await this.initPromise;\n\n    const storage = await this.getStorage();\n    const task = await storage.getTask(taskId);\n    if (!task) {\n      throw new Error(`Task not found: ${taskId}`);\n    }\n    if (task.status !== 'running') {\n      throw new Error(`Cannot restart task in status '${task.status}' (expected 'running')`);\n    }\n\n    if (context) {\n      this.registerTaskContext(task.id, context);","sourceCodeStart":448,"sourceCodeEnd":484,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/background-tasks/manager.ts#L448-L484","documentation":"restart() is refused while the BackgroundTaskManager is shutting down (shuttingDown flag set, e.g. during shutdown()/process exit). Starting new task executions during teardown could orphan work or race cleanup, so the manager throws instead.","triggerScenarios":"Calling manager.restart(taskId) after manager.shutdown() was invoked or while the process/manager is mid-shutdown (SIGTERM handlers, graceful close, tests tearing down the Mastra instance).","commonSituations":"A request handler tries to restart a task during server graceful shutdown; an async operation completes after tests shut the manager down and then calls restart.","solutions":["Move restart calls before shutdown, or reject queued restart requests once shutdown has begun.","Catch this error and either re-create the manager/Mastra instance or defer the restart to a fresh process.","Check an app-level 'shutting down' flag before issuing restart calls in signal handlers."],"exampleFix":"// before\nawait manager.restart(taskId); // during SIGTERM handling\n// after\nif (!isShuttingDown) {\n  await manager.restart(taskId);\n} else {\n  pendingRestarts.push(taskId); // replay after restart of process\n}","handlingStrategy":"validation","validationCode":"// app-level gate (manager.shuttingDown is private)\nlet managerShuttingDown = false;\nasync function safeRestart(taskId) {\n  if (managerShuttingDown) throw new Error('deferred: manager shutting down');\n  return manager.restart(taskId);\n}\n// set managerShuttingDown = true before calling manager.shutdown()","typeGuard":null,"tryCatchPattern":"try {\n  await manager.restart(taskId);\n} catch (e) {\n  if (e.message === 'BackgroundTaskManager is shutting down, cannot restart tasks') {\n    deferredRestarts.push(taskId); // replay after new manager is up\n  } else throw e;\n}","preventionTips":["Route all task mutations through a gate that is closed during shutdown/SIGTERM handling.","Drain or queue task operations before calling shutdown().","In tests, stop issuing background operations after afterEach teardown."],"tags":["background-tasks","shutdown","lifecycle"],"backgroundTag":"manager-shutting-down","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}