{"record":{"id":"cb934896cec77758","repo":"mastra-ai/mastra","slug":"mastra-get-internal-workflow-by-id-not-found","errorCode":"MASTRA_GET_INTERNAL_WORKFLOW_BY_ID_NOT_FOUND","errorMessage":"Workflow with id ${String(id)} not found","messagePattern":"Workflow with id (.+?) not found","errorType":"error_code","errorClass":"MastraError","httpStatus":404,"severity":"error","filePath":"packages/core/src/mastra/index.ts","lineNumber":3638,"sourceCode":"    const workflows = this.#workflows as Record<string, AnyWorkflow> | undefined;\n    if (workflows?.[workflowId]) return true;\n    return Object.values(workflows ?? {}).some(w => w.id === workflowId);\n  }\n\n  __getInternalWorkflow(id: string, runId?: string): AnyWorkflow {\n    let workflow: AnyWorkflow | undefined;\n    if (runId) {\n      workflow = this.#internalMastraWorkflows[`${id}:${runId}`];\n      if (workflow) {\n        this.#touchRunScopedWorkflow(id, runId);\n      } else {\n        workflow = this.#internalMastraWorkflows[id];\n      }\n    } else {\n      workflow = this.#internalMastraWorkflows[id];\n    }\n    if (!workflow) {\n      throw new MastraError({\n        id: 'MASTRA_GET_INTERNAL_WORKFLOW_BY_ID_NOT_FOUND',\n        domain: ErrorDomain.MASTRA,\n        category: ErrorCategory.SYSTEM,\n        text: `Workflow with id ${String(id)} not found`,\n        details: {\n          status: 404,\n          workflowId: String(id),\n        },\n      });\n    }\n\n    return workflow;\n  }\n\n  /**\n   * @internal Records the tracing context for an evented workflow run so the\n   * event processor can nest step spans under the run's parent span. The\n   * `currentSpan` is non-serializable, so it is held here rather than passed","sourceCodeStart":3620,"sourceCodeEnd":3656,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/mastra/index.ts#L3620-L3656","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst wf = mastra.getInternalWorkflow('my-custom-workflow'); // user workflow, not internal\n// after\nconst wf = mastra.getWorkflow('my-custom-workflow');","handlingStrategy":"try-catch","validationCode":"const allWfs = mastra.listWorkflows?.() ?? {};\nif (!(id in allWfs) && !(id in (mastra.listInternalWorkflows?.() ?? {}))) {\n  throw new Error(`Workflow ${id} is not registered (internal or user)`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const wf = mastra.getInternalWorkflow(id);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'MASTRA_GET_INTERNAL_WORKFLOW_BY_ID_NOT_FOUND') {\n    // try mastra.getWorkflow(id) or verify the id/instance\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["workflow","internal-workflow","not-found","mastra-api"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}