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

​
Plugin Not Showing Up

If Monk does not appear in your coding agent after installing the plugin:
  • Reload or restart the agent — most hosts only load plugins at startup.
  • 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 /plugins and confirm Monk is installed from the monk-plugins marketplace.
  • 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.
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

​
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, auth, 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, update the plugin itself (see update paths per agent) 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 into AWS/GCP/Azure/DigitalOcean 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

Monk has full context about the failure and can usually pinpoint 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 Takes Too Long

Cloud provisioning typically takes 3–8 minutes. If it runs longer than 15 minutes:
  • Cloud provider API throttling can slow things down during peak hours
  • If it is stuck, ask Monk for status: /monk what is happening with the cluster
  • As a last resort, cancel and retry — Monk cleans up partial infrastructure automatically

​
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 CLT — but 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 containers automatically. 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 Monk — it can often adjust the container configuration it generated
  • 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