magus v0.4.2 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
1 min read

MGS3008: no workspace root found

magus walked up from the current directory looking for a workspace marker (magus.yaml) or a contiguous run of project markers (magusfile.buzz, magusfiles/, go.mod) and found neither before running out of ancestors.

magus: could not locate workspace root (no magus.yaml, magusfiles/, magusfile.buzz,
  or go.mod found); run `magus init` to bootstrap one

Why

Every magus command needs a workspace to operate against. Discovery walks upward from the current directory: the nearest magus.yaml wins outright, and otherwise the walk tracks the outermost directory of an unbroken run of project markers, so a stray magusfile in an unrelated ancestor (a home directory, /tmp) cannot silently adopt everything beneath it. When neither is found by the time the walk reaches the filesystem root, there is nothing for the command to run against.

This is the most common failure on a first run: a fresh checkout, or a directory that was never set up as a magus workspace at all.

Fix

Run magus init in the directory you meant to work from. It writes magus.yaml (to $XDG_CONFIG_HOME/magus/ by default, or the current directory with --local) and stubs a magusfile.buzz when none exists, which is exactly what this discovery walk is looking for.

If you meant to be somewhere else, cd into the right directory (or pass --root <path>) before running the command again - discovery only walks upward from where it starts.

See also

  • magus init: bootstraps the workspace this code reports missing.
  • MGS1021: the other early-failure code, for a workspace that DOES exist but whose declared floor this binary cannot meet.
sandbox diagnosticsLanding page for the sandbox that confines magus spells to the workspace, plus its MGS2xxx diagnostics for denied reads, writes, execs, and env leaks. magus DocumentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground. MGS1002: spell import shadowedFires when a spells/<name> in a nested project is shadowed by a same-named spell higher in the tree, because spell imports resolve root-wins so the deeper definition is dead. MGS1015: cross-project dependency names an unresolvable projectFires at load when ctx.needs references a target through a project import whose path does not resolve to a path in this workspace, so the dependency edge would be dropped and the affected set would silently under-report.
MGS3008workspace rootmagus initfirst runmagus.yaml
Last updated (4f8cc295)
Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Ward

A coded diagnostic that inspects a resolved op and nudges or blocks an anti-pattern before it runs. See wards.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Conventions

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.