What causes "No ${instanceUsersPath} file found" in windmill-labs/windmill?

Create/export the file first: run the instance users export command (e.g. `wmill user instance ... export` or equivalent) to generate instanceUsersPath.

windmill-labs/windmill · warning

No ${instanceUsersPath} file found

Error message

No ${instanceUsersPath} file found

What it means

`readInstanceUsers` in the instance-user sync command parses the local instanceUsers file (path from instanceUsersPath, e.g. instance_users.yaml) with yamlParseFile. If parsing throws — typically because the file does not exist — it logs this warning and returns an empty user list rather than failing the command. The instance sync then behaves as if there are no local users defined.

Source

Thrown at cli/src/commands/user/user.ts:436

    log.info("Pulling users from instance...");
    await writeFile(
      instanceUsersPath,
      yamlStringify(remoteUsers as any),
      "utf-8"
    );
    log.info(colors.green(`Users written to ${instanceUsersPath}`));
  }
}

export async function readInstanceUsers(opts: InstanceSyncOptions) {
  let localUsers: ExportedUser[] = [];

  await checkInstanceUsersPath(opts);

  try {
    localUsers = (await yamlParseFile(instanceUsersPath)) as ExportedUser[];
  } catch {
    log.warn(`No ${instanceUsersPath} file found`);
  }
  return localUsers;
}

export async function readInstanceGroups(opts: InstanceSyncOptions) {
  let localGroups: InstanceGroup[] = [];

  checkInstanceGroupsPath(opts);

  try {
    localGroups = (await yamlParseFile(
      instanceGroupsPath
    )) as ExportedInstanceGroup[];
  } catch {
    log.warn(`No ${instanceGroupsPath} file found`);
  }
  return localGroups;
}

View on GitHub (pinned to e474e8803c)

Solutions

Create/export the file first: run the instance users export command (e.g. `wmill user instance ... export` or equivalent) to generate instanceUsersPath.
Verify the path option/cwd matches where the YAML actually lives (`ls <instanceUsersPath>`).
If an empty list is genuinely acceptable, ignore the warning.
Check file permissions if the file exists but cannot be read.

Example fix

// before
wmill user instance sync  # No instance_users.yaml file found
// after
wmill user instance ... export  # writes instance_users.yaml
wmill user instance sync

Defensive patterns

Strategy: fallback

Validate before calling

// Before running instance sync, check the file exists:
import fs from 'fs';
if (!fs.existsSync(instanceUsersPath)) {
  throw new Error(`Run the export first: ${instanceUsersPath} missing`);
}

Type guard

function isExportedUsers(v: unknown): v is ExportedUser[] {
  return Array.isArray(v) && v.every((u) => typeof u === 'object' && u !== null && 'email' in u);
}

Try / catch

let localUsers: ExportedUser[] = [];
try {
  localUsers = (await yamlParseFile(instanceUsersPath)) as ExportedUser[];
} catch {
  log.warn(`No ${instanceUsersPath} file found — continuing with empty list`);
}

Prevention

Run the instance users export before any instance sync command
Run commands from the directory containing the YAML, or pass an explicit path
Add a CI check that the exported file exists before sync jobs
Verify file permissions when the file should exist

When it happens

Trigger: Running `wmill user ...` commands that call localUsers/readInstanceUsers (e.g. instance user sync) when the instance users YAML file has not been exported/created at the expected path.

Common situations: Fresh checkout missing the instance users export; wrong --instance-users-path or cwd so the file isn't found; deleted file after a failed export; typo in filename.

Related errors

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