MGS1021: workspace requires a newer magus

The workspace declares the oldest magus that can run it, and the running binary is older than that. The check runs before any magusfile is evaluated, so nothing has been loaded yet.

[MGS1021] this workspace requires magus >= 0.4.0 and this build is v0.3.0.
Upgrade the binary (`magus self update`), or if this is CI, raise the pinned
version in your magus setup step. The workspace declares the floor in magus.yaml
(required_version).
  see: .../MGS1021.md

Why

magus adds features additively, so a magusfile that worked keeps working on every later release (see compatibility). The reverse is not promised: a magusfile using a host module or a magus\project key added last month cannot run on a binary built before it.

Without a declared floor, that situation surfaces from wherever the magusfile first touched the missing thing:

import "xml": module not found

which reads like a typo, not like an out-of-date tool. It sends people looking at their magusfile instead of their magus.

The floor has to be declared rather than derived, and the reason is worth being explicit about: the binary reporting the error is the old one. It cannot look up which release introduced xml, because it has never heard of that release. No table shipped in a newer magus can help, since the newer magus is not the one running. A declared minimum is the only claim an old binary can evaluate against a future it does not know about. Terraform's required_version, Go's go directive, and npm's engines all exist for exactly this.

Resolution

Two fixes, and which one you want depends on where you hit it.

Locally, upgrade the binary:

magus self update

In CI, raise the pinned version in your setup step, since CI deliberately runs a pinned, checksum-verified release rather than whatever is newest:

- uses: egladman/magus/.github/actions/setup-magus@main
  with:
    version: v0.4.0

Or lower the floor, if it was raised by mistake. The floor lives in magus.yaml:

required_version: ">= 0.4.0"

The value is a semver constraint. ">= 0.4.0" is the usual form; the key may be omitted entirely to declare no floor. A constraint magus cannot parse is reported under this same code rather than passing silently, so a typo cannot quietly read as "no floor declared".

A floor should name a RELEASED version. A build between releases describes itself from the last tag: a tree 42 commits past v0.3.0 reports v0.3.0-42-gabc and compares as 0.3.0, so a floor set to a version that has not shipped yet rejects builds from source, including of the commit that raised the floor.

A binary built from this checkout

MGS1021 also fires when a binary built from the checkout it runs in predates that checkout's sources, typically after a pull or a merge: the magusfile names something the binary has never heard of. That binary cannot rebuild itself, since every command it runs loads the same tree, so the message names a relink instead:

go build -o magus ./cmd/magus
./magus run go-build .

The bootstrap does the same in one command, and the guard allows it, alone on its line, over a ./magus that cannot load the tree. There is no need to move the old binary aside first:

GOEXPERIMENT=jsonv2 go run -trimpath ./cmd/magus run go-build --no-cache .

If the link fails with undefined: in generated code, the committed generated files are behind the sources because a merge kept one side of them. Restoring either side's copy keeps the mismatch. Regenerate them with what the *_generate targets run, in this order, then link again:

go generate ./cmd/magus-utils
go generate ./internal/spell/...
go run ./cmd/magus-utils jobschema -out internal/job/gen
go generate ./internal/langservice
go generate ./std/...
go generate ./internal/handler/mcp

In magus's own repository the agent guard allows exactly these commands and the bootstrap, each alone on its line, while the workspace fails with MGS1021, and refuses them again once it loads. See the raw-tool rule.

What this is not

• Not a compatibility break. Nothing that worked has stopped working. This is the absence of forward compatibility, which magus does not promise and neither does any comparable tool.
• Not a floor check against a dev build. An unstamped local build reports its version as unknown and is exempt from the floor: it is usually newer than any release, and blocking local development against a floor the working tree just raised would be backwards. A dev build that predates its checkout still gets MGS1021 the other way, above.
• Not raised for a library caller. magus.Open without magus.WithVersion supplies no version, so there is nothing to compare and the check passes.

See also

• compatibility: what magus promises across versions, and where the floor fits.
• magus version: the running build's version.
• magus doctor: reports a floor lower than what the workspace requires.