mastra-ai/mastra · error

Bound Factory work item not found.

Error message

Bound Factory work item not found.

What it means

Once the session's binding is validated, the tool loads the bound work item via `storage.get({orgId, id: binding.workItemId})` and throws if it no longer exists. The binding references an item that was deleted (or is not visible in this org), so no transition can be performed. This is a referential-integrity failure between the run binding and the work-items store.

Source

Thrown at mastracode/factory/src/rules/tools.ts:86

          sessions: options.sessions,
        });
        const currentAddress = currentResolution?.address ?? null;
        const toolCallId = execution.agent?.toolCallId;
        if (!currentAddress || !toolCallId) {
          throw new Error('Factory transitions require an authenticated bound agent tool call.');
        }
        const binding = await options.storage.findActiveRunBinding(currentAddress);
        // Authority is the work item this session is bound to, not the individual
        // binding row. Handing the next role its turn in an existing session
        // rotates the binding, and tools built for the previous role stay live
        // across that rotation; keying on row identity would strand the run that
        // the rotation exists to start. Re-pointing a session at a different item
        // is the hijack this guards against.
        if (!binding || binding.workItemId !== availableBinding.workItemId) {
          throw new Error('Factory agent binding is unavailable, revoked, or no longer matches this session.');
        }
        const item = await options.storage.get({ orgId: binding.orgId, id: binding.workItemId });
        if (!item) throw new Error('Bound Factory work item not found.');
        const triageType =
          'triageType' in input && isFactoryTriageType(input.triageType) ? input.triageType : undefined;

        const result = await options.transitionService.transition({
          orgId: binding.orgId,
          factoryProjectId: binding.factoryProjectId,
          workItemId: binding.workItemId,
          board: boardForSource(item.externalSource?.type),
          stage,
          expectedRevision,
          actor: { type: 'agent', bindingId: binding.id, role: binding.role },
          ingress: { type: 'agent', identity: `${binding.id}:${toolCallId}` },
          cause: rationale,
          ...(triageType ? { triageType } : {}),
        });

        // A phase EXIT is the natural moment to ask what was worth keeping:
        // run the subconscious curator directly on the session's thread.

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the work item exists via storage.get with the binding's exact orgId and id; recreate it if it was deleted and the run is still wanted.
2. Delete or expire the stale run binding and restart the run so binding and item are recreated together.
3. Confirm both the bindings and work-items domains use the same storage instance/database and orgId; fix config if they diverge.
4. Check for deletion automation (linear/github sync, cleanup jobs) racing the agent run and disable or rescope it.

const item = await storage.get({ orgId: binding.orgId, id: binding.workItemId });
if (!item) throw new Error('Bound work item missing; refresh binding or recreate item before transitioning.');

function workItemExists(
  item: { id: string; orgId: string } | null | undefined,
): item is { id: string; orgId: string } {
  return item != null && typeof item.id === 'string' && typeof item.orgId === 'string';
}

try {
  await transitionTool.execute(input, execution);
} catch (e) {
  if (e instanceof Error && e.message === 'Bound Factory work item not found.') {
    // mark binding stale, skip the transition, alert maintainers
  } else throw e;
}

When it happens

Trigger: `options.storage.get` for the binding's orgId and workItemId returns null/undefined at tool execution time — the work item was deleted, purged, hard-migrated to another org, or the storage domain is pointed at a different dataset than the one the binding was written to.

Common situations: A maintainer or automation deleted/closed-and-purged the issue/PR-backed item while the agent run was in flight; environment mismatch (dev binding row pointing at prod items); storage backend swapped or re-seeded without cleaning run bindings.

Related errors

• Version-control installation not found.
• Factory decision is not linked to a work item.
• Factory work item not found.
• Factory binding ${binding.id} has no authenticated session o
• The related work item chain contains a cycle.

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