mastra-ai/mastra · warning · HTTPException

Background task not found

Error message

Background task not found

What it means

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.

Source

Thrown at packages/server/src/server/handlers/background-tasks.ts:82

    return bgManager.listTasks(params);
  },
});

export const GET_BACKGROUND_TASK_ROUTE = createRoute({
  method: 'GET',
  path: '/background-tasks/:backgroundTaskId',
  responseType: 'json' as const,
  pathParamSchema: backgroundTaskIdPathParams,
  responseSchema: backgroundTaskResponseSchema,
  summary: 'Get a background task by ID',
  description: 'Returns a background task by ID.',
  tags: ['Background Tasks'],
  requiresAuth: true,
  handler: async ({ mastra, backgroundTaskId }) => {
    const bgManager = mastra.backgroundTaskManager;
    if (!bgManager) {
      // Background tasks not enabled — the task can't exist.
      throw new HTTPException(404, { message: 'Background task not found' });
    }

    const task = await bgManager.getTask(backgroundTaskId);
    if (!task) {
      throw new HTTPException(404, { message: 'Background task not found' });
    }
    return task;
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify backgroundTaskManager is configured/enabled on the Mastra instance if you expect tasks to exist.
2. Double-check the backgroundTaskId against the value returned when the task was created.
3. Confirm you're querying the same environment/database where the task was enqueued.
4. Handle 404 gracefully in polling clients — treat it as terminal ('task not found') rather than retrying indefinitely.

Example fix

// before: infinite polling
while (true) { const t = await getTask(id); if (t.status === 'done') break; }

// after: handle 404 as terminal
const res = await fetch(`/api/background-tasks/${id}`);
if (res.status === 404) throw new Error(`Background task ${id} not found (wrong ID, disabled feature, or pruned)`);

// Confirm background tasks are enabled before polling
if (!mastra.backgroundTaskManager) {
  throw new Error('Background tasks are not enabled on this Mastra instance');
}

function hasBackgroundTaskManager(mastra: Mastra): mastra is Mastra & { backgroundTaskManager: NonNullable<Mastra['backgroundTaskManager']> } {
  return typeof (mastra as any).backgroundTaskManager !== 'undefined' && (mastra as any).backgroundTaskManager !== null;
}

try {
  const task = await getBackgroundTask(id);
} catch (e) {
  if (e.status === 404 && /Background task not found/.test(e.message)) {
    // Terminal: wrong ID, feature disabled, or record pruned — stop polling
    markTaskUnknown(id);
    return;
  }
  throw e;
}

When it happens

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

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

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Model "${modelId}" is not available. Available models: ${ids
• ACP connection is not initialized
• Model "${this.options.model}" is not available. Available mo
• ClaudeSDKAgent resumeData must include either sessionId or c
• ClaudeSDKAgent resumeData.sessionId must be a string.

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/30bd6779130d162e. Report an issue: GitHub.