Upgrading walkerOS clients

The walkerOS app (app.walkeros.io) keeps one minimum version for the walkerOS CLI. A CLI below that version gets 426 Upgrade Required instead of an answer. This page explains how to recognise it and how to recover.

How the CLI identifies itself

Every request from the walkerOS CLI to the app carries three headers:

Header	Example
User-Agent	walkeros-cli/4.9.0
X-WalkerOS-Client	cli
X-WalkerOS-Client-Version	4.9.0

The app uses them to decide whether the caller meets the minimum version, and to name the package to upgrade in its answer. A request without these headers (curl, a browser, your own HTTP client) is never refused for its version, and the local walkerOS MCP server sends none of them, so the minimum does not apply to it.

The 426 response

When the client is below the minimum version, the app answers 426 Upgrade Required with this body (the version numbers are an example):

{
  "error": {
    "code": "CLIENT_OUTDATED",
    "message": "This endpoint requires @walkeros/cli >= 4.10.0 (you are on 4.9.0).",
    "minVersion": "4.10.0",
    "clientVersion": "4.9.0",
    "client": "cli",
    "upgrade": "The latest @walkeros/cli release on npm meets this requirement.",
    "docs": "https://walkeros.io/docs/upgrading"
  }
}

walkeros api prints this body on stdout, names the status and the message in one line on stderr, and exits 1. The hosted walkerOS MCP server needs no upgrade: it ships with the app.

Upgrade checklist

• CLI (@walkeros/cli): npm install -g @walkeros/cli@latest (or bump the version in your project's package.json if you installed locally).
• MCP server (@walkeros/mcp): update the pinned version in your MCP client config, or bump @walkeros/mcp in your project and restart the client.
• Runtime image: rebuild on a newer walkeros/flow version and redeploy. Each image tag is the version of the @walkeros/runner it contains; keep it in step with the @walkeros/cli that builds your flows.

After upgrading, re-run the failing command. If the 426 persists, your client is still below the minimum version. Check the installed version against the minVersion field of the answer.

Why this exists

The app raises the minimum only on a deliberate cut, for example when a release removes commands that older clients still call. Rather than letting an older client fail in a confusing way, the app answers 426 with the version to move to, so the fix is one upgrade away.