Troubleshooting

Start here:

polyforge doctor

It checks that mise is present and trusted, that the wrappers resolved on PATH, and that the configuration fragments parse.

polyforge is not recognised as a command

Cause. Almost always a shell that has not reloaded its profile.

Activation writes to your shell profile; the session that ran it does not see the change.

1. Open a new shell.

2. If it still fails, re-run activation and check for errors:

   Windows (PowerShell)

   .\polyforge.ps1 activate

   Linux / macOS / WSL

   ./polyforge.sh activate

3. Confirm the profile was actually written — $PROFILE on Windows, ~/.bashrc or ~/.zshrc on POSIX. A shell using a different profile file than the one activation wrote to is the usual second cause.

The command works, but only in some directories

That is by design. The wrappers walk up the tree to find the workspace root and refuse to run outside a PolyForge repository. Any depth inside the repo is fine.

mise refuses to run: config not trusted

Cause. mise trust has not run on this machine, or was reset.

polyforge activate

This is a security boundary, not a bug: mise config can define tasks and environment variables, so it will not execute config it has not been told to trust — and a repository cannot trust itself.

Note

Trust is per machine. A new laptop always needs it, even with the same repository and the same account.

A tool is declared but “not found”

Cause. It has not been installed. auto_install = false means declaring a tool never fetches it.

polyforge status     # confirm the gap
polyforge install    # close it

See explicit installs.

I added a conf.d fragment and nothing changed

Check, in order:

1. The file ends in .toml and is inside .config/mise/conf.d/.
2. You ran polyforge install. There is no watch mode.
3. No other fragment declares the same tool. A later-sorting file wins silently — see the merge model.
4. polyforge doctor reports no parse errors.

publish or forge new fails

These need the GitHub CLI, authenticated:

gh auth status
gh auth login

get commands never need gh — if only publishing fails, this is why.

A project did not come back with get all

Cause. It is not in the registry on this machine.

Publishing writes to polyforge.registry.toml, but committing that change is a separate step. Check the machine you published from:

git status              # in the polyforge repo
git log -1 -- polyforge.registry.toml

If the entry was never committed and pushed, this clone does not know the repository exists. See content separation.

learn next created the wrong day

It is filling a gap. next always creates the lowest missing day — if day02 was deleted, it comes back before day07 does.

learn list go     # shows exactly what next would create

Disk usage is growing

Installs and caches live in .cache/, which is git-ignored.

polyforge clean          # empty .cache
polyforge clean --all    # also mise implode — removes every installed toolchain

--all is not a cleanup

--all removes mise itself and every toolchain on the machine, not just PolyForge’s. Use it to reset a machine, not to reclaim a few gigabytes.

Something else

Open an issue on GitHub with the output of polyforge doctor and your platform.