What causes "Workflow with id ${String(id)} not found" in mastra-ai/mastra?

Ensure the feature that creates the internal workflow (e.g. an agent network run) has initialized before calling getInternalWorkflow.

mastra-ai/mastra · error · MastraError

MASTRA_GET_INTERNAL_WORKFLOW_BY_ID_NOT_FOUND

MASTRA_GET_INTERNAL_WORKFLOW_BY_ID_NOT_FOUND

Error message

Workflow with id ${String(id)} not found

What it means

mastra.getInternalWorkflow(id) looks up the id in internal Mastra workflows (with special handling when the id belongs to a storage/prisma-backed namespace); if no workflow is found it throws this SYSTEM-category 404 MastraError. Internal workflows are framework-created workflows (e.g. agent network/workflow internals), distinct from user-registered workflows.

Source

Thrown at packages/core/src/mastra/index.ts:3638

    const workflows = this.#workflows as Record<string, AnyWorkflow> | undefined;
    if (workflows?.[workflowId]) return true;
    return Object.values(workflows ?? {}).some(w => w.id === workflowId);
  }

  __getInternalWorkflow(id: string, runId?: string): AnyWorkflow {
    let workflow: AnyWorkflow | undefined;
    if (runId) {
      workflow = this.#internalMastraWorkflows[`${id}:${runId}`];
      if (workflow) {
        this.#touchRunScopedWorkflow(id, runId);
      } else {
        workflow = this.#internalMastraWorkflows[id];
      }
    } else {
      workflow = this.#internalMastraWorkflows[id];
    }
    if (!workflow) {
      throw new MastraError({
        id: 'MASTRA_GET_INTERNAL_WORKFLOW_BY_ID_NOT_FOUND',
        domain: ErrorDomain.MASTRA,
        category: ErrorCategory.SYSTEM,
        text: `Workflow with id ${String(id)} not found`,
        details: {
          status: 404,
          workflowId: String(id),
        },
      });
    }

    return workflow;
  }

  /**
   * @internal Records the tracing context for an evented workflow run so the
   * event processor can nest step spans under the run's parent span. The
   * `currentSpan` is non-serializable, so it is held here rather than passed

View on GitHub (pinned to 75dd419e61)

Solutions

Ensure the feature that creates the internal workflow (e.g. an agent network run) has initialized before calling getInternalWorkflow.
Use mastra.getWorkflow(id) for user-registered workflows; reserve getInternalWorkflow for framework-created ones.
Verify the id matches exactly what was registered internally (log Object.keys or the registry when debugging).
Confirm you are calling it on the same Mastra instance that created the workflow.

Example fix

// before
const wf = mastra.getInternalWorkflow('my-custom-workflow'); // user workflow, not internal
// after
const wf = mastra.getWorkflow('my-custom-workflow');

Defensive patterns

Strategy: try-catch

Validate before calling

const allWfs = mastra.listWorkflows?.() ?? {};
if (!(id in allWfs) && !(id in (mastra.listInternalWorkflows?.() ?? {}))) {
  throw new Error(`Workflow ${id} is not registered (internal or user)`);
}

Try / catch

try {
  const wf = mastra.getInternalWorkflow(id);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MASTRA_GET_INTERNAL_WORKFLOW_BY_ID_NOT_FOUND') {
    // try mastra.getWorkflow(id) or verify the id/instance
  }
  throw e;
}

Prevention

Use getWorkflow for user-registered workflows and getInternalWorkflow only for framework-created ones
Trigger the feature that creates the internal workflow before fetching it
Call on the same Mastra instance that created the workflow
Log available workflow ids when debugging lookups

When it happens

Trigger: Calling mastra.getInternalWorkflow('some-id') where the id is not present in #internalMastraWorkflows — e.g. the internal workflow was never created, was created on a different Mastra instance, or the id includes a namespace prefix that resolves against a different registry.

Common situations: Fetching an internal workflow by id copied from storage/trace output before the corresponding agent/network run initialized it; querying a workflow registered as a regular workflow via getInternalWorkflow instead of getWorkflow; tests constructing a fresh Mastra without running the feature that creates the internal workflow.

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

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