Skip to main content
This page covers problems you might hit while getting started with Monk, from installation through your first deployment. For runtime issues with already-deployed applications, see the runtime troubleshooting guide.
Your coding agent can troubleshoot the plugin install for you. Start with /monk check installation status and let it diagnose. The cases below are the ones that occasionally need your hands: upgrading the plugin, restarting the agent, or fixing something on your machine.

​
The installer didn’t finish

Run it again with --dry-run to see what it found and what it would do, without changing anything:
  • It refused a download. Every download is checked against Monk’s signed release list. A refusal means the file didn’t match, usually because a proxy or a half-finished download changed it. Your existing install is kept. Run the installer again; if it keeps refusing, report it.
  • An agent failed and the others worked. Each agent is set up on its own, so one failure doesn’t stop the rest. The summary names the failed agent and the command to run, for example signing in to that agent’s own CLI first.
  • It printed a plan and stopped. With no terminal to ask you on (in a script or CI), it changes nothing unless you add --yes.
  • Your agent isn’t in the plan. The installer looks for the agent’s command and config folder. Open the agent once, or follow its steps in Agents.
Every config file the installer edits is backed up first to ~/.monk/agent/setup-backups/.

​
Plugin not showing up

If Monk does not appear in your coding agent after installing:
  • Reload or restart the agent. Most hosts only load plugins at startup. The installer’s summary lists how for each agent.
  • Claude Code: run /reload-plugins, then /mcp and confirm Monk is listed.
  • Cursor: open Settings → Tools & MCP and confirm Monk is listed and enabled.
  • Codex: run codex plugin list and confirm monk@monk-plugins is installed, then restart Codex.
  • Antigravity: confirm ~/.monk/bin/monk-agent status reports running and that ~/.gemini/config/mcp_config.json has a monk entry. A project must be open: plugins load in workspace context.
  • Agents without a plugin (VS Code, Zed, Warp and the others): check that the agent’s config file has the monk entry from Agents, then restart the agent.
If the MCP server shows as offline, check that no other process is blocking 127.0.0.1:7419, then restart the agent so the plugin can start monk-agent again.

​
Sign-in problems

When you sign in, Monk opens a browser tab for authentication. If the flow does not complete:
  • Make sure your default browser is not blocking pop-ups from monk.io
  • Try signing in with a different browser
  • If you are behind a corporate proxy or VPN, check that monk.io and auth.monk.io are not blocked
  • In Claude Code, run /mcp and use the MCP authentication prompt; in Codex, run codex mcp login monk; in Cursor, use the MCP login flow for the monk server. Other agents are listed in Agents

​
Setup incomplete

If the plugin installed but Monk reports that runtime setup is incomplete, ask your coding agent:
Monk inspects the local runtime (CLI, daemon, sign-in, workspace state), tells you what is wrong, and either fixes it or walks you through the fix. Common causes: missing system dependencies, network connectivity, file permission issues, or the container runtime not running.

​
Agent does not see Monk (MCP issues)

If your coding agent cannot find Monk’s MCP tools:
  • Restart the agent after installing the plugin. Some hosts only read MCP config at startup
  • Run /mcp (Claude Code, Codex) or check Settings → Tools & MCP (Cursor) to verify the connection
  • Confirm monk-agent is running: ~/.monk/bin/monk-agent status
  • Confirm nothing else is occupying 127.0.0.1:7419

​
Outdated plugin or runtime

The plugin requires a minimum monkd version and prompts to upgrade older installs. Accept the prompt, or upgrade through your package manager, then restart your coding agent. If problems appear after things used to work, run the installer again to update Monk and its plugins and restart or reload the agent. Most hosts only pick up plugin changes on restart.

​
Credential errors

Monk reports credentials as invalid or deployment fails with permission errors:
  • Double-check the values: copy-paste errors and trailing spaces are the most common cause
  • Verify in the provider console: log in to your provider and confirm the key is active and not expired
  • Check permissions: compare attached policies against the minimum permissions listed in the cloud credential guides
  • Azure client secret expired: secrets have an expiry date; create a new one in App registrations
  • GCP key disabled: check the service account status in IAM & Admin
Update credentials through your agent:

​
Deployment fails

If a deployment does not complete:
1

Ask your agent what went wrong

Your agent reads the deployment status and logs from Monk to find the cause.
2

Check credentials

Credential issues are the most common cause. See the section above.
3

Check cloud quotas

Some cloud providers have default limits on VMs, elastic IPs, or load balancers. If Monk reports a quota error, request a limit increase in your provider console.
4

Check region availability

Not all instance types are available in all regions. If Monk reports an instance type error, try a different region or let Monk choose.

​
Cluster creation seems stuck

How long provisioning takes depends on your provider and region. If it seems stuck:
  • Ask Monk for status: /monk what is happening with the cluster
  • Provider API throttling or quota limits can slow or block creation. Check your provider console.
  • If a create was interrupted, ask Monk to delete the half-created cluster before you try again, and check your provider console for anything left behind.

​
OS-specific issues

Xcode Command Line Tools errorsAfter a macOS upgrade, you may see “invalid active developer path” or Homebrew commands fail. Monk detects this automatically and reinstalls the Command Line Tools. If the auto-fix doesn’t work:
Then run /monk check installation status again.Homebrew not found after installOn Apple Silicon Macs, Homebrew installs to /opt/homebrew/bin. On Intel Macs, it’s /usr/local/bin. Make sure your shell profile exports the correct path, then restart your coding agent so it picks up the updated PATH.Podman machine conflictMonk needs its own Podman machine named “monk”. If another Podman machine is already running, the installer asks you to stop it first. You can do this manually:

​
Container runtime issues

Monk builds your container images from the Dockerfiles your coding agent wrote. If the build fails:
  • Make sure the container runtime is running on your machine
  • On Linux, confirm your user has the right permissions to run containers
  • If the build fails on a specific dependency, ask your agent to read the build output and fix the Dockerfile
  • Large projects may need more memory allocated to the container runtime

​
Still stuck?

Ask Monk directly through your coding agent. It has context about your environment and can often diagnose the problem faster than searching docs. If nothing helps, run /monk report a bug. It collects environment details automatically and sends them to the engineering team.

Help & support

Bug reports, feature requests, community forum, and direct contact