windmill-labs/windmill · error · Error

Could not find a workspace mapped to branch \`${opts.fromBra

Error message

Could not find a workspace mapped to branch \`${opts.fromBranch}\` in wmill.yaml's workspaces section. Pass the base branch your fork should be based on (e.g. the branch bound to the parent workspace).

What it means

When `--from-branch <B>` is given, B must be a base branch — i.e. a branch explicitly mapped to a workspace in wmill.yaml's workspaces section — because the fork clones that workspace. If no workspace in the config maps to B, the CLI cannot know which workspace to fork and throws.

Source

Thrown at cli/src/commands/workspace/fork.ts:84

        `Omit --from-branch to create a fresh fork branch with \`git checkout -b\`.`,
      );
    }
    if (isBaseBranch(currentBranch)) {
      throw new Error(
        `Refusing to rename your current branch \`${currentBranch}\` — it looks like a base branch (mapped to a workspace in wmill.yaml, or main/master). ` +
        `Check out the disposable working branch you want to convert first.`,
      );
    }
    if (getOriginalBranchForWorkspaceForks(currentBranch)) {
      // Current branch is itself a fork branch (wm-fork/<base>/<old-id>).
      // Renaming it onto the new fork branch would detach the existing fork.
      throw new Error(
        `Refusing to rename your current branch \`${currentBranch}\` — it is already a fork branch. ` +
        `To fork a fork, omit --from-branch: \`wmill workspace fork\` bases the new fork on this fork's original branch and creates a fresh fork branch without renaming.`,
      );
    }
    if (!findWorkspaceByGitBranch(config.workspaces, opts.fromBranch)) {
      throw new Error(
        `Could not find a workspace mapped to branch \`${opts.fromBranch}\` in wmill.yaml's workspaces section. ` +
        `Pass the base branch your fork should be based on (e.g. the branch bound to the parent workspace).`,
      );
    }
    clonedBranchName = opts.fromBranch;
    renameCurrent = true;
  } else if (originalBranchIfForked) {
    // Fork of a fork: link to the original branch; user checks out a new branch.
    log.info(`You are creating a fork of a fork. The branch will be linked to the original branch this was forked from, i.e. \`${originalBranchIfForked}\`, for all settings and overrides.`);
    clonedBranchName = originalBranchIfForked;
    renameCurrent = false;
  } else if (isBaseBranch(currentBranch)) {
    // On a base branch: base the fork on it; user checks out a fresh fork branch.
    clonedBranchName = currentBranch;
    renameCurrent = false;
  } else {
    // On a non-base working branch: offer to base the fork on it and rename it.
    clonedBranchName = await resolveWorkingBranchBase(config, opts, currentBranch);

View on GitHub (pinned to e474e8803c)

Solutions

  1. Check `wmill.yaml` workspaces section and pass a branch that is actually mapped to the parent workspace
  2. Fix the branch name typo (compare with `git branch -a` and the wmill.yaml entries)
  3. Add/reinstate the workspace-to-branch mapping in wmill.yaml for the intended base branch

Example fix

// before
wmill workspace fork --from-branch develop  # no mapping in wmill.yaml
// after
wmill workspace fork --from-branch main  # main is mapped to the prod workspace in wmill.yaml
Defensive patterns

Strategy: validation

Validate before calling

const mapped = config.workspaces?.find(w => w.gitBranch === opts.fromBranch);
if (opts.fromBranch && !mapped) {
  throw new Error(`Branch '${opts.fromBranch}' is not mapped to a workspace in wmill.yaml.`);
}
await createWorkspaceFork(opts, name);

Type guard

function branchIsMapped(branch: string, workspaces: { gitBranch?: string }[] | undefined): boolean {
  return !!workspaces?.some(w => w.gitBranch === branch);
}

Try / catch

try {
  await createWorkspaceFork(opts, name);
} catch (e) {
 if ((e as Error).message.includes("mapped to branch") && e.message.includes('workspaces section')) {
    console.error('Pass a base branch listed under workspaces in wmill.yaml.');
  } else throw e;
}

Prevention

When it happens

Trigger: Running `wmill workspace fork --from-branch <B>` where B is a real git branch but has no corresponding entry under workspaces in wmill.yaml (typo in branch name, branch mapping deleted, or pointing at a non-base feature branch).

Common situations: Typos in the branch name; teammate deleted the wmill.yaml mapping; pointing --from-branch at a local-only branch never bound to a workspace; stale local wmill.yaml after pulling config changes.

Related errors

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/47bbb9209e546b06. Report an issue: GitHub.