windmill-labs/windmill · warning

⚠️ --branch/--env is deprecated. Use --workspace instead.

Error message

⚠️  --branch/--env is deprecated. Use --workspace instead.

What it means

A deprecation warning from the sync config-resolution code. The `--branch`/`--env` flags historically selected which workspace entry in wmill.yaml to use; they have been superseded by `--workspace`. Sync still works, but the flag will eventually be removed.

Source

Thrown at cli/src/commands/sync/sync.ts:3552

  if ((opts as any).jsonOutput) log.setSilent(true);
  const originalCliOpts = { ...opts };
  opts = await mergeConfigWithConfigFile(opts);

  // --include-secrets overrides skipSecrets from wmill.yaml
  if ((originalCliOpts as any).includeSecrets) {
    opts.skipSecrets = false;
  }

  // Resolve workspace name for config lookups.
  // --branch resolves git branch → workspace name (deprecated but still supported).
  // --workspace selects a workspace config entry by name when it matches one,
  // regardless of --base-url. If it doesn't match any entry it's treated as a
  // profile/credential selector only.
  const hasExplicitCredentials = !!opts.baseUrl;
  let wsNameForConfig: string | undefined;

  if (opts.branch && !hasExplicitCredentials && !branchDeprecationWarned) {
    log.warn("⚠️  --branch/--env is deprecated. Use --workspace instead.");
    branchDeprecationWarned = true;
  }

  wsNameForConfig = resolveWsNameForConfigFromFlags(opts);

  if (!opts.branch && opts.workspace && !hasExplicitCredentials) {
    // Warn if override doesn't match a config key, or mismatches the auto-detected branch
    warnWorkspaceOverride(opts, opts.workspace);
  }

  // Validate workspace configuration early. Skip when ANY explicit flag is set
  // (even a --workspace value that doesn't match a config key — the user opted
  // out of branch-based auto-detection).
  try {
    await validateBranchConfiguration(opts, wsNameForConfig ?? opts.workspace);
  } catch (error) {
    if (error instanceof Error && error.message.includes("overrides")) {
      log.error(error.message);

View on GitHub (pinned to e474e8803c)

Solutions

1. Replace `--branch <name>` with `--workspace <name>` in your command/scripts.
2. Update CI pipelines and documentation to use --workspace.
3. Verify the resolved workspace matches what --branch previously selected (`wmill workspace list`).
4. No immediate action required — behavior is unchanged; the warning is informational until removal.

Example fix

// before
wmill sync pull --branch prod
// after
wmill sync pull --workspace prod

if (args.includes("--branch") || args.includes("--env")) {
  throw new Error("--branch/--env is deprecated; use --workspace");
}

function usesDeprecatedSyncFlags(args: string[]): boolean {
  return args.includes("--branch") || args.includes("--env");
}

try {
  await runSyncCommand(args);
} catch (e) {
  if (String(e).includes("deprecated")) {
    console.error("Update the script to use --workspace");
  } else throw e;
}

When it happens

Trigger: Running `wmill sync pull`/`push` (or subcommands sharing this resolver) with `--branch <name>` or `--env <name>` and no --base-url (i.e. no explicit credentials), on the first such invocation in the process (branchDeprecationWarned gates repeats).

Common situations: Old CI scripts or docs written before the flag rename; muscle memory from older CLI versions; copy-pasted commands from stale README files.

Related errors

• Workspace folder not found, are you in the right directory?
• Not a fileset resource path: ${changePath}
• No resource metadata file found for fileset resource: ${chan
• Found ${wrongFormatPaths.length} directory(ies) using ${foun
• pointerErrors.join("\n")

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