---
title: "MGS3008: no workspace root found"
description: Fires when magus walks up from the current directory and finds no magus.yaml, magusfiles/, magusfile.buzz, or go.mod anywhere in an unbroken ancestor chain.
tags: [MGS3008, workspace root, magus init, first run, magus.yaml]
---

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

```text
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](../magusfile/MGS1021.md): the other early-failure code, for a
  workspace that DOES exist but whose declared floor this binary cannot meet.