windmill-labs/windmill · error · UnknownLockVersionError

wmill-lock.yaml is at unknown version "${conf.version}". Thi

Error message

wmill-lock.yaml is at unknown version "${conf.version}". This was written by a newer wmill CLI; please upgrade with `wmill upgrade`. Refusing to operate to avoid corrupting the lockfile.

What it means

wmill-lock.yaml carries a version field identifying which lockfile schema wrote it. If the version is present but not in the CLI's KNOWN_LOCK_VERSIONS, the CLI throws UnknownLockVersionError and refuses to operate, because an older CLI cannot safely interpret a newer lockfile format. This protects the lockfile from being downgraded or corrupted.

Source

Thrown at cli/src/utils/metadata.ts:1259

  if (inMemoryLock) return inMemoryLock;
  let parsed: unknown;
  try {
    parsed = await yamlParseFile(WMILL_LOCKFILE);
  } catch {
    const lock: Lock = { locks: {}, version: CURRENT_LOCK_VERSION };
    await writeFile(WMILL_LOCKFILE, yamlStringify(lock, yamlOptions), "utf-8");
    log.info(colors.green("wmill-lock.yaml created"));
    return lock;
  }
  if (typeof parsed != "object" || parsed == null) {
    throw new MalformedLockfileError(
      "wmill-lock.yaml is malformed (expected an object). " +
      "Refusing to operate to avoid corrupting the lockfile.",
    );
  }
  const conf = parsed as Lock;
  if (conf.version != null && !KNOWN_LOCK_VERSIONS.includes(conf.version)) {
    throw new UnknownLockVersionError(
      `wmill-lock.yaml is at unknown version "${conf.version}". This was ` +
      `written by a newer wmill CLI; please upgrade with \`wmill upgrade\`. ` +
      `Refusing to operate to avoid corrupting the lockfile.`,
    );
  }
  return conf;
}

function v2LockPath(path: string, subpath?: string) {
  const normalizedPath = normalizeLockPath(path);
  if (subpath) {
    return `${normalizedPath}+${normalizeLockPath(subpath)}`;
  } else {
    return normalizedPath;
  }
}
export async function checkifMetadataUptodate(
  path: string,

View on GitHub (pinned to e474e8803c)

Solutions

1. Upgrade the CLI with `wmill upgrade` (or your package manager) so it recognizes the lockfile version
2. If you cannot upgrade, have the teammate/machine with the newer CLI regenerate the lockfile with a compatible version
3. As a last resort, delete wmill-lock.yaml and let your (older) CLI regenerate it, accepting loss of locked dependency state
4. Check for mixed CLI versions across team/CI and pin a consistent wmill version

Example fix

// shell
// before
$ wmill sync pull   # errors: unknown lock version
// after
$ wmill upgrade
$ wmill sync pull   # succeeds

const lock = yaml.parse(await readFile("wmill-lock.yaml", "utf-8"));
if (lock?.version != null && lock.version > CURRENT_LOCK_VERSION) {
  console.warn("Lockfile was written by a newer wmill CLI — run `wmill upgrade` first.");
}

function hasKnownVersion(v: unknown): v is { version?: number } {
  return typeof v === "object" && v !== null &&
    ((v as any).version == null || KNOWN_LOCK_VERSIONS.includes((v as any).version));
}

try {
  await wmillSyncPush();
} catch (e) {
  if (e instanceof UnknownLockVersionError) {
    await runWmillUpgrade(); // then retry
  } else throw e;
}

When it happens

Trigger: Running a wmill command that reads the lockfile after wmill-lock.yaml was written by a newer CLI release whose lock version is not recognized by the installed CLI.

Common situations: Upgrading the lockfile with a newer wmill on one machine (or CI) then using an older CLI on another; switching branches where a teammate regenerated the lockfile with a newer CLI; running a stale CLI in Docker while the host CLI is current.

Related errors

• Cannot regenerate lock for flow ${remote_path}: missing inli
• Failed to queue flow dependencies job: ${queueResponse.statu
• Failed to poll flow dependencies job ${jobId}: ${e?.message
• Failed to generate lockfile: ${message}
• Failed to generate lockfile: ${message}

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