{"record":{"id":"1235b832f660292b","repo":"mastra-ai/mastra","slug":"error-message-dynamic-materializeerror","errorCode":null,"errorMessage":"error.message (dynamic; MaterializeError)","messagePattern":"error\\.message \\(dynamic; MaterializeError\\)","errorType":"error_code","errorClass":"FactoryDispatchError","httpStatus":null,"severity":"error","filePath":"mastracode/factory/src/routes/surface.ts","lineNumber":236,"sourceCode":"          parentWorkItemId: input.item.parentWorkItemId,\n          title: input.item.title,\n          stages: ['intake'],\n          sessions: input.item.sessions,\n          metadata: input.item.metadata,\n        },\n      },\n    });\n  } catch (error) {\n    if (error instanceof FactoryDispatchError) throw error;\n    if (error instanceof FactorySourceSessionResolutionError) {\n      const code = error.reason === 'connection' ? 'source_control_missing' : 'source_repository_missing';\n      throw new FactoryDispatchError(code, error.message, { cause: error });\n    }\n    if (error instanceof SourceControlConnectionNotFoundError) {\n      throw new FactoryDispatchError('source_control_missing', error.message, { cause: error });\n    }\n    if (error instanceof MaterializeError) {\n      throw new FactoryDispatchError(MATERIALIZE_FAILURE_CODE[error.code], error.message, { cause: error });\n    }\n    throw error;\n  }\n}\n\n/**\n * Build the {@link IntegrationContext} handed to an integration when the\n * factory collects its capabilities (routes, workers). One shape everywhere:\n * `assembleFactoryApiRoutes` uses it per registration, and `MastraFactory` uses it\n * when collecting integration workers at finalize.\n */\nexport function buildIntegrationContext(\n  deps: Pick<\n    FactoryApiRoutesDeps,\n    | 'controller'\n    | 'publicOrigin'\n    | 'auth'\n    | 'sandbox'","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/routes/surface.ts#L218-L254","documentation":"prepareFactoryRuleBinding wraps lower-level materialization failures into a FactoryDispatchError whose code is derived from the MaterializeError code via MATERIALIZE_FAILURE_CODE, preserving the original message and cause. This translation exists so API routes surface a consistent dispatch-error taxonomy instead of leaking internal MaterializeError types. You see the original materialization message as error.message.","triggerScenarios":"Calling a factory API route (assembled via assembleFactoryApiRoutes) that internally calls prepareFactoryRuleBinding, when the linked-item materialization step throws a MaterializeError (e.g. source-control or work-item creation failure mapped by MATERIALIZE_FAILURE_CODE).","commonSituations":"Source control connection misconfigured or revoked, linked work item cannot be materialized on the external system (missing repo/permissions), or stale binding pointing at a deleted external item.","solutions":["Read error.cause (the original MaterializeError) and its code to find the concrete materialization failure.","Verify the factory's source control connection is configured, authenticated, and points at a reachable repository.","Check the referenced work item still exists on the external system and the credentials have write access.","Retry the route call after fixing the external state; the error is a wrapped snapshot, not a retryable signal by itself."],"exampleFix":"// before: raw handling, lost taxonomy\ntry { await dispatchRoute(req); } catch (e) { console.error(e); }\n// after: inspect wrapped cause\ntry {\n  await dispatchRoute(req);\n} catch (e) {\n  if (e instanceof FactoryDispatchError) {\n    console.error('dispatch failed:', e.message, 'cause:', e.cause);\n  } else throw e;\n}","handlingStrategy":"try-catch","validationCode":"if (!sourceControlConnection) throw new Error('Configure the source control connection before invoking factory dispatch routes.');","typeGuard":"function isFactoryDispatchError(e: unknown): e is FactoryDispatchError {\n  return e instanceof FactoryDispatchError;\n}","tryCatchPattern":"try {\n  await callFactoryRoute();\n} catch (e) {\n  if (isFactoryDispatchError(e)) {\n    log('materialization failure', e.message, e.cause);\n  } else throw e;\n}","preventionTips":["Validate source control connectivity before triggering binding routes.","Always inspect e.cause on FactoryDispatchError for the root MaterializeError.","Keep external work items and connections in sync to avoid materialization failures."],"tags":["factory","materialization","wrapped-error","api-route"],"backgroundTag":"materialization-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}