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.

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)

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
• WORKSPACE_PROJECT_PERMISSION_DENIED

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