Help

Troubleshooting

What to try when the installer is blocked, a model will not connect, a run pauses, a feature is disabled or a terminal tool is not found.

Last updated 1 November 2026

Install

What you see	What to do
“Windows protected your PC”	The installer is not code-signed yet. Check its SHA-256 against the download card, then choose More info → Run anyway. See Install Maxtkn.
The installer asks to download something	It is fetching Microsoft’s WebView2 runtime. Stay connected until it finishes.
The download link does not work	Links are private and last five minutes. Go back to the website and press Download again.
No download card on the website	No build has been published yet. Join the early access list and choose Windows.

What you see	What to do
Test connection fails	Read the message: it quotes the provider. Check the key, the endpoint address and that the model name exists on that service.
The key is rejected as expired or invalid	Make a new key at the provider and paste it again under Settings → Providers.
A run is “paused”	The provider hit a rate limit, quota, key or network problem. The run continues by itself when the provider says when; otherwise fix the cause and press Resume.
The Claude Code or Codex row says “not signed in”	Open an ordinary terminal, run `claude` and sign in with `/login` (or run `codex login`), then press Check again.
“Not found on this computer”	The tool is not on your PATH. Install it, then reopen Maxtkn or press Check again.
A model says “cost unknown”	It has no price in the built-in list. It still works; budgets just cannot count it.

What you see	What to do
“Waiting for you…”	An approval, a plan or a question needs an answer. Check the thread, or Mission control → Needs you.
Nothing happens for several minutes	A run with no activity for six minutes is stopped and flagged. Start it again, perhaps with a smaller request.
The team stops partway through a big file	Very large single files can be cut off. Ask for the file in smaller parts, or for edits instead of a whole rewrite.
A check says “not run”	It could not run here, for example there was no browser available. It is never counted as a pass.
A change you rejected comes back	The next run is told about rejected changes. If the team tries again, say plainly in your next message that you do not want it. See Review changes and undo.

What you see	What to do
The Isolated copy switch is disabled	Hover it for the reason. Usually git is missing, the folder is not a repository, or there is no saved version yet. Save one in the Versions tab.
Scheduling a task is unavailable	Quick chats cannot be scheduled. Save the chat as a project first.
A scheduled task shows “Needs your OK”	The task was changed since you allowed it. Press Review and allow.
A scheduled task did not run	Tasks run only while Maxtkn is open. A missed one runs once, late, if that switch is on; otherwise it is recorded as missed.
Preview shows nothing for a project with a dev server	Start the project’s server from the Preview tab and agree to its command. The page appears once the server answers.
Many terminals is missing	It needs the desktop app and git.
A terminal tool cannot be started	The dialog says which command was not found. Install the tool and sign in once in an ordinary terminal, or use Custom command.
Run commands in isolation says it cannot start	Docker, Podman or your WSL distribution is not running or missing a piece. Check it works says which. Nothing runs on your computer until it is fixed.

What you see	What to do
Exit code 2	An unknown option or a missing value. Run with `--help`.
Exit code 3	An approval was needed and denied. See the list at the end of the output, then allow that tool with `--yes-to <tool>` if you accept it.
Exit code 4	Cancelled or timed out. Raise `--timeout` or make the request smaller.
Exit code 5	A goal ran out of rounds, time or money. Raise `--max-rounds` or `--max-usd`, or make the goal more specific.
A missing key message	Set the environment variable it names. See The maxtkn command line.
`--worktree` refuses	It needs git, a repository and a first commit.

Open the thread’s ⋯ menu and use Share → Save this thread to keep a record of what happened.
Look at the changelog in case the problem is already fixed in a newer build.
Reply to the early access email with what you saw and what you expected.

Something missing or wrong? Maxtkn is early-access software and these pages change with it. The changelog lists what changed in each build.