⚠️ WARNING: Multiple workspaces map to git branch '${branch

Error message

⚠️  WARNING: Multiple workspaces map to git branch '${branch}': ${names.join(", ")}.\n   Only the first ('${names[0]}') will be used during auto-detection. Use --workspace to select explicitly.

What it means

This warning from `validateBranchConfiguration` fires when two or more entries in the `workspaces` section of `wmill.yaml` resolve to the same effective git branch (via `gitBranch` or their name default). During branch-based auto-detection the CLI can only pick one workspace, so it deterministically uses the first one declared and tells the user to disambiguate with `--workspace`. The command still proceeds; it is a configuration-ambiguity advisory.

Source

Thrown at cli/src/core/conf.ts:446

    );
    return;
  }

  // Warn if multiple workspaces map to the same git branch
  const branchToWsNames = new Map<string, string[]>();
  for (const name of getWorkspaceNames(workspaces)) {
    const entry = workspaces[name] as WorkspaceEntryConfig;
    const branch = getEffectiveGitBranch(name, entry);
    const existing = branchToWsNames.get(branch);
    if (existing) {
      existing.push(name);
    } else {
      branchToWsNames.set(branch, [name]);
    }
  }
  for (const [branch, names] of branchToWsNames) {
    if (names.length > 1) {
      log.warn(
        `⚠️  WARNING: Multiple workspaces map to git branch '${branch}': ${names.join(", ")}.\n` +
          `   Only the first ('${names[0]}') will be used during auto-detection. Use --workspace to select explicitly.`
      );
    }
  }

  // Current branch must match a configured workspace's gitBranch
  if (currentBranch && !findWorkspaceByGitBranch(workspaces, currentBranch)) {
    const wsNames = getWorkspaceNames(workspaces);
    const availableInfo = wsNames
      .map((n) => {
        const entry = workspaces[n] as WorkspaceEntryConfig;
        const branch = getEffectiveGitBranch(n, entry);
        return branch !== n ? `${n} (gitBranch: ${branch})` : n;
      })
      .join(", ");

    // In interactive mode, offer to create a workspace entry

View on GitHub (pinned to e474e8803c)

Solutions

Give each workspace a unique `gitBranch` value in `wmill.yaml` (one workspace per branch).
Remove the stale/duplicate workspace entry that maps to the same branch.
Pass `--workspace <name>` explicitly on push/pull to choose which workspace to use regardless of ambiguity.

Example fix

# before
workspaces:
  prod:
    gitBranch: main
  prod-old:
    gitBranch: main

# after
workspaces:
  prod:
    gitBranch: main
  staging:
    gitBranch: develop

Defensive patterns

Strategy: validation

Validate before calling

// check for duplicate effective branches across workspace entries
import { readConfigFile, getWorkspaceNames } from "./conf.ts"; // or parse YAML yourself
const config = await readConfigFile();
const seen = new Map<string, string>();
for (const name of getWorkspaceNames(config.workspaces ?? {})) {
  const branch = (config.workspaces as any)[name]?.gitBranch ?? name;
  if (seen.has(branch)) throw new Error(`Branch ${branch} mapped by both ${seen.get(branch)} and ${name}`);
  seen.set(branch, name);
}

Prevention

Enforce one workspace per git branch as a team convention.
Search the whole `workspaces` block for `gitBranch` duplicates before committing changes.
When renaming a workspace, delete the old entry in the same commit.
In CI, use explicit `--workspace` so ambiguity never matters.

When it happens

Trigger: Running `wmill push`/`wmill pull` in a git repo where `wmill.yaml` has e.g. `workspaces: { a: { gitBranch: main }, b: { gitBranch: main } }` — both `a` and `b` map to branch `main`. Not shown when `--workspace`/`--skip-branch-validation` is used.

Common situations: Duplicating a workspace entry to change a setting (e.g. different sync paths for the same branch), renaming a workspace without removing the old entry, or a copy-paste of a workspace block without updating its `gitBranch`.

Related errors

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