windmill-labs/windmill · warning

Warning: Workspace name "${workspaceName}" contains filesyst

Error message

Warning: Workspace name "${workspaceName}" contains filesystem-unsafe characters (/ \ : * ? " < > | .) and was sanitized to "${sanitizedName}". This may cause collisions with other similarly named branches.

What it means

toWorkspaceSpecificPath builds branch/workspace-specific sync paths by sanitizing the workspace name: characters / \ : * ? " < > | . are replaced with underscores. If the name contained any of those characters (i.e. sanitization changed it), a console.warn explains the rename and that it can collide with other similarly named workspaces. It is informational — sync continues with the sanitized path — but two workspaces like feature/x and feature_x will map to the same directory and clobber each other's files.

Source

Thrown at cli/src/core/specific_items.ts:304

    if (basePathMatch && specificItems.resources) {
      const basePath = basePathMatch[1] + '.resource.yaml';
      return matchesPatterns(basePath, specificItems.resources);
    }
  }

  return false;
}

/**
 * Convert a base path to a workspace-specific path
 */
export function toWorkspaceSpecificPath(basePath: string, workspaceName: string): string {
  // Sanitize branch name to be filesystem-safe
  const sanitizedName = workspaceName.replace(/[\/\\:*?"<>|.]/g, '_');

  // Warn about potential collisions if sanitization occurred
  if (sanitizedName !== workspaceName) {
    console.warn(`Warning: Workspace name "${workspaceName}" contains filesystem-unsafe characters (/ \\ : * ? " < > | .) and was sanitized to "${sanitizedName}". This may cause collisions with other similarly named branches.`);
  }

  // Check for folder meta file pattern: folder.meta.{yaml,json} -> folder.workspaceName.meta.{yaml,json}
  const folderMetaMatch = basePath.match(/^(.*)\/folder\.meta\.(yaml|json)$/);
  if (folderMetaMatch) {
    return `${folderMetaMatch[1]}/folder.${sanitizedName}.meta.${folderMetaMatch[2]}`;
  }

  // Check for settings.{yaml,json}: settings.{ext} -> settings.workspaceName.{ext}
  const settingsMatch = basePath.match(/^settings\.(yaml|json)$/);
  if (settingsMatch) {
    return `settings.${sanitizedName}.${settingsMatch[1]}`;
  }

  // Check for resource file pattern (e.g., .resource.file.ini)
  const resourceFileMatch = basePath.match(/^(.+?)(\.resource\.file\..+)$/);

  let extension: string;

View on GitHub (pinned to e474e8803c)

Solutions

1. Rename the workspace/branch to contain only filesystem-safe characters (letters, digits, -, _).
2. If the branch name must contain slashes, accept the sanitized path but ensure no other branch sanitizes to the same string.
3. Set the workspace name explicitly in CI to a pre-sanitized value (e.g. replace '/' with '-' before invoking wmill).
4. Verify which directory files are being read from/written to after the warning and update scripts/docs accordingly.

Example fix

// before (CI)
BRANCH="${GITHUB_REF#refs/heads/}"   # feature/add-login
wmill sync push --workspace-name "$BRANCH"

// after
BRANCH=$(echo "${GITHUB_REF#refs/heads/}" | tr '/' '-')
wmill sync push --workspace-name "$BRANCH"

const UNSAFE = /[/\\:*?"<>|.]/;
if (UNSAFE.test(workspaceName)) {
  throw new Error(`workspace name '${workspaceName}' contains filesystem-unsafe characters; sanitize it before syncing`);
}

function isFilesystemSafeName(name: string): boolean {
  return /^[A-Za-z0-9_-]+$/.test(name);
}

const safeName = workspaceName.replace(/[/\\:*?"<>|.]/g, "-");
console.log(`syncing as workspace '${safeName}'`);
await $`wmill sync push --workspace-name ${safeName}`;

When it happens

Trigger: Calling toWorkspaceSpecificPath (directly, or via getWorkspaceSpecificPath / branchSpecific / findFilesetResourceFile during sync pull/push) with a workspaceName containing any of / \ : * ? " < > | . — most commonly Git branch names with slashes like feature/add-login.

Common situations: Using a Git branch name as the workspace name in a branch-deployed sync flow (feature/xyz becomes feature_xyz); Windows-incompatible names; names containing dots from semver-like tags (v1.2.3 becomes v1_2_3); two branches `a/b` and `a_b` silently sharing one directory.

Related errors

• File not found: ${filePath}
• Workspace folder not found, are you in the right directory?
• Directory not found: ${targetDirectory}
• Path is not a directory: ${targetDirectory}
• file path must refer to a file.

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