mastra-ai/mastra · error · FactoryDispatchError

error.message (dynamic; MaterializeError)

Error message

error.message (dynamic; MaterializeError)

What it means

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.

Source

Thrown at mastracode/factory/src/routes/surface.ts:236

          parentWorkItemId: input.item.parentWorkItemId,
          title: input.item.title,
          stages: ['intake'],
          sessions: input.item.sessions,
          metadata: input.item.metadata,
        },
      },
    });
  } catch (error) {
    if (error instanceof FactoryDispatchError) throw error;
    if (error instanceof FactorySourceSessionResolutionError) {
      const code = error.reason === 'connection' ? 'source_control_missing' : 'source_repository_missing';
      throw new FactoryDispatchError(code, error.message, { cause: error });
    }
    if (error instanceof SourceControlConnectionNotFoundError) {
      throw new FactoryDispatchError('source_control_missing', error.message, { cause: error });
    }
    if (error instanceof MaterializeError) {
      throw new FactoryDispatchError(MATERIALIZE_FAILURE_CODE[error.code], error.message, { cause: error });
    }
    throw error;
  }
}

/**
 * Build the {@link IntegrationContext} handed to an integration when the
 * factory collects its capabilities (routes, workers). One shape everywhere:
 * `assembleFactoryApiRoutes` uses it per registration, and `MastraFactory` uses it
 * when collecting integration workers at finalize.
 */
export function buildIntegrationContext(
  deps: Pick<
    FactoryApiRoutesDeps,
    | 'controller'
    | 'publicOrigin'
    | 'auth'
    | 'sandbox'

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read error.cause (the original MaterializeError) and its code to find the concrete materialization failure.
2. Verify the factory's source control connection is configured, authenticated, and points at a reachable repository.
3. Check the referenced work item still exists on the external system and the credentials have write access.
4. Retry the route call after fixing the external state; the error is a wrapped snapshot, not a retryable signal by itself.

Example fix

// before: raw handling, lost taxonomy
try { await dispatchRoute(req); } catch (e) { console.error(e); }
// after: inspect wrapped cause
try {
  await dispatchRoute(req);
} catch (e) {
  if (e instanceof FactoryDispatchError) {
    console.error('dispatch failed:', e.message, 'cause:', e.cause);
  } else throw e;
}

if (!sourceControlConnection) throw new Error('Configure the source control connection before invoking factory dispatch routes.');

function isFactoryDispatchError(e: unknown): e is FactoryDispatchError {
  return e instanceof FactoryDispatchError;
}

try {
  await callFactoryRoute();
} catch (e) {
  if (isFactoryDispatchError(e)) {
    log('materialization failure', e.message, e.cause);
  } else throw e;
}

When it happens

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

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

Related errors

• ${initial.code}: ${initial.reason}
• ${moved.code}: ${moved.reason}
• Factory decision is not linked to a work item.
• Factory work item not found.
• session_unavailable

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