{"record":{"id":"30bd6779130d162e","repo":"mastra-ai/mastra","slug":"background-task-not-found","errorCode":null,"errorMessage":"Background task not found","messagePattern":"Background task not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"warning","filePath":"packages/server/src/server/handlers/background-tasks.ts","lineNumber":82,"sourceCode":"    return bgManager.listTasks(params);\n  },\n});\n\nexport const GET_BACKGROUND_TASK_ROUTE = createRoute({\n  method: 'GET',\n  path: '/background-tasks/:backgroundTaskId',\n  responseType: 'json' as const,\n  pathParamSchema: backgroundTaskIdPathParams,\n  responseSchema: backgroundTaskResponseSchema,\n  summary: 'Get a background task by ID',\n  description: 'Returns a background task by ID.',\n  tags: ['Background Tasks'],\n  requiresAuth: true,\n  handler: async ({ mastra, backgroundTaskId }) => {\n    const bgManager = mastra.backgroundTaskManager;\n    if (!bgManager) {\n      // Background tasks not enabled — the task can't exist.\n      throw new HTTPException(404, { message: 'Background task not found' });\n    }\n\n    const task = await bgManager.getTask(backgroundTaskId);\n    if (!task) {\n      throw new HTTPException(404, { message: 'Background task not found' });\n    }\n    return task;\n  },\n});\n","sourceCodeStart":64,"sourceCodeEnd":92,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/background-tasks.ts#L64-L92","documentation":"Thrown as a 404 by the background-task GET route when either the Mastra instance has no backgroundTaskManager (background tasks not enabled, so the task cannot exist) or bgManager.getTask(id) returns nothing for the given ID. Both cases intentionally return the same message.","triggerScenarios":"Requesting a background task by ID when background tasks are not enabled on the server (no backgroundTaskManager configured), or the ID is wrong/typo'd, or the task record was pruned/expired from the store, or querying a different environment/DB than the one that created the task.","commonSituations":"Polling a task status after its record was cleaned up; copy-paste ID mismatch between environments (staging vs prod); background tasks feature not enabled in the deployment config; checking immediately after server restart against a non-persistent store.","solutions":["Verify backgroundTaskManager is configured/enabled on the Mastra instance if you expect tasks to exist.","Double-check the backgroundTaskId against the value returned when the task was created.","Confirm you're querying the same environment/database where the task was enqueued.","Handle 404 gracefully in polling clients — treat it as terminal ('task not found') rather than retrying indefinitely."],"exampleFix":"// before: infinite polling\nwhile (true) { const t = await getTask(id); if (t.status === 'done') break; }\n\n// after: handle 404 as terminal\nconst res = await fetch(`/api/background-tasks/${id}`);\nif (res.status === 404) throw new Error(`Background task ${id} not found (wrong ID, disabled feature, or pruned)`);","handlingStrategy":"try-catch","validationCode":"// Confirm background tasks are enabled before polling\nif (!mastra.backgroundTaskManager) {\n  throw new Error('Background tasks are not enabled on this Mastra instance');\n}","typeGuard":"function hasBackgroundTaskManager(mastra: Mastra): mastra is Mastra & { backgroundTaskManager: NonNullable<Mastra['backgroundTaskManager']> } {\n  return typeof (mastra as any).backgroundTaskManager !== 'undefined' && (mastra as any).backgroundTaskManager !== null;\n}","tryCatchPattern":"try {\n  const task = await getBackgroundTask(id);\n} catch (e) {\n  if (e.status === 404 && /Background task not found/.test(e.message)) {\n    // Terminal: wrong ID, feature disabled, or record pruned — stop polling\n    markTaskUnknown(id);\n    return;\n  }\n  throw e;\n}","preventionTips":["Persist the task ID returned at enqueue time; never reconstruct or guess IDs.","Enable/configure backgroundTaskManager if your workflows depend on background execution.","Use the same environment/database for enqueue and status polling.","Cap polling retries and treat 404 as a terminal state."],"tags":["background-tasks","http-404","not-found"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}