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 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.

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.

Appendix: 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)