nexu-io/open-design · error · Error

design system backing project is unavailable

Error message

design system backing project is unavailable

What it means

Thrown by the design-system backing project preparer when neither `resolveProjectId` nor (if provided) `ensureProjectId` returns a usable project id, or when the returned id fails `projectExists`. The preparer is the exact-Workspace authorization gate before any Team hub mutation, so a missing backing project aborts the share rather than publishing an orphan design system.

Solutions

1. Verify the backing project for the design system still exists in the project store.
2. If auto-creation is intended, ensure `ensureProjectId` is wired in the preparer options and can materialize the project under the request's workspace identity.
3. Check the resolver (`resolveProjectId`) returns the correct project id for the resource id and scope.
4. Investigate SQLite/project-store health if the project exists in the hub but `projectExists` returns false.

// Before sharing, confirm the backing project resolves and exists:
const projectId = await resolveProjectId(resourceId, scope);
if (!projectId || !projectExists(projectId)) {
  if (!ensureProjectId) throw new Error('backing project missing and auto-create is disabled');
  const ensured = await ensureProjectId(resourceId, scope);
  if (!ensured || !projectExists(ensured)) {
    throw new Error('cannot prepare backing project for share');
  }
}
await share(resourceId, scope);

try {
  await linkedShare.share(resourceId, scope);
} catch (err) {
  if (err instanceof Error && /backing project is unavailable/.test(err.message)) {
    // re-create the backing project or wire ensureProjectId, then retry
  }
  throw err;
}

When it happens

Trigger: Calling `share` on a linked design-system resource whose backing project was deleted, never created, or whose resolver returned null and `ensureProjectId` is not configured (or also returned null/empty).

Common situations: The backing project row was removed out-of-band while the design system record remained. Auto-creation (`ensureProjectId`) is disabled in the deployment. A resolver bug returns null for a resource that should have a project. Database/SQLite issues making `projectExists` return false.

Related errors

• design system backing project belongs to another workspace
• workspace_resource_share_denied
• design system backing project publish failed
• WORKSPACE_RESOURCE_AUTHORITY_UNAVAILABLE
• Project not found

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/057960ebd12aeb68. Report an issue: GitHub.

Appendix: source

Thrown at apps/daemon/src/design-systems/team-project-share.ts:96

  return error;
}

/**
 * Build the exact-Workspace project half of the linked-resource saga.
 * Authority is checked before the coordinator publishes the design system,
 * and each remote-project/local-projection pair compensates itself before
 * rejecting.
 */
export function createDesignSystemBackingProjectPreparer(
  options: CreateDesignSystemBackingProjectPreparerOptions,
): CreateLinkedProjectTeamResourceShareServiceOptions['prepare'] {
  return async (resourceId, scope) => {
    let projectId = (await options.resolveProjectId(resourceId, scope))?.trim() ?? '';
    if ((!projectId || !options.projectExists(projectId)) && options.ensureProjectId) {
      projectId = (await options.ensureProjectId(resourceId, scope))?.trim() ?? '';
    }
    if (!projectId || !options.projectExists(projectId)) {
      throw new Error('design system backing project is unavailable');
    }
    const workspaceId = scope.principal.teamId;
    const memberId = scope.principal.memberId;
    const binding = options.getProjectBinding(projectId);
    if (binding?.workspaceId && binding.workspaceId !== workspaceId) {
      throw new Error('design system backing project belongs to another workspace');
    }
    if (binding?.createdByWorkspaceMemberId !== memberId) {
      throw new TeamResourceShareForbiddenError();
    }
    options.onPrepared?.({ resourceId, projectId, scope });
    return {
      projectId,
      transition: async (visibility) => {
        if (visibility === 'team') {
          const published = await options.publishProject(projectId, scope);
          if (published.version == null) {
            throw new Error('design system backing project publish failed');

View on GitHub (pinned to 5be4028344)