windmill-labs/windmill · error · Error

Could not resolve workspace from branch name. Make sure you

Error message

Could not resolve workspace from branch name. Make sure you are in a git repo to use workspace forks

What it means

After determining the base branch, the CLI must resolve the parent Windmill workspace that the fork will clone. `tryResolveBranchWorkspace` matches the current (or base) git branch against the workspaces in wmill.yaml / the CLI config. If nothing matches — no workspace with a matching gitBranch setting and no explicit workspace context — the fork cannot proceed and this error is thrown.

Source

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

    clonedBranchName = await resolveWorkingBranchBase(config, opts, currentBranch);
    renameCurrent = true;
  }

  // Resolve the parent workspace. When the base differs from the current
  // branch (the rename workflows), resolve via the base branch's workspace;
  // otherwise use plain branch resolution.
  let workspace;
  if (clonedBranchName === currentBranch) {
    workspace = await tryResolveBranchWorkspace(opts);
  } else {
    const baseMatch = findWorkspaceByGitBranch(config.workspaces, clonedBranchName);
    workspace = baseMatch
      ? await tryResolveBranchWorkspace(opts, baseMatch[0])
      : await tryResolveBranchWorkspace(opts);
  }

  if (!workspace) {
    throw new Error("Could not resolve workspace from branch name. Make sure you are in a git repo to use workspace forks");
  }

  log.info(`You are forking workspace (${workspace.workspaceId})`)

  if (opts.workspace) {
    log.info(
      colors.red.bold(
        "! Workspace needs to be specified as positional argument, not as option."
      )
    );
    return;
  }

  const token = workspace.token;

  if (!token) {
    throw new Error("Not logged in. Please run 'wmill workspace add' first.");
  }

View on GitHub (pinned to e474e8803c)

Solutions

Run `wmill workspace add` to register the workspace and generate/map it to your current branch in wmill.yaml
Switch to the branch that is mapped to the workspace you want to fork, then run the command
Manually add a gitBranch mapping for the current branch under workspaces in wmill.yaml
Pass the workspace explicitly if your CLI version supports it, or use --from-branch with a mapped base branch

Example fix

// before (unmapped branch)
git switch brand-new-branch && wmill workspace fork  # error
// after
wmill workspace add https://instance user token  # registers + maps workspace
git switch brand-new-branch && wmill workspace fork

Defensive patterns

Strategy: validation

Validate before calling

const current = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
const ws = config.workspaces?.find(w => w.gitBranch === current);
if (!ws) {
  throw new Error(`No workspace mapped to branch '${current}'. Run 'wmill workspace add' first.`);
}
await createWorkspaceFork(opts, name);

Type guard

function resolveWorkspaceForBranch<T extends { gitBranch?: string }>(branch: string, workspaces: T[] | undefined): T | null {
  return workspaces?.find(w => w.gitBranch === branch) ?? null;
}

Try / catch

try {
  await createWorkspaceFork(opts, name);
} catch (e) {
  if ((e as Error).message.includes('Could not resolve workspace from branch')) {
    console.error('Register the workspace: `wmill workspace add <remote> <name> <token>`.');
  } else throw e;
}

Prevention

Run `wmill workspace add` right after cloning a repo
Check out the branch mapped to the workspace you intend to fork
Verify mappings with `wmill workspace list` before forking in CI

When it happens

Trigger: Running `wmill workspace fork` from a branch that is not mapped to any workspace in the CLI config (and not a fork-of-fork branch), so branch-to-workspace resolution returns undefined.

Common situations: Cloned a repo but never ran `wmill workspace add` so wmill.yaml has no workspaces; checked out a brand-new feature branch before mapping it; wmill.yaml missing (config not synced); CI environment lacking the local workspace config.

Related errors

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