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.

​
Extension Not Activating

Monk only activates when a workspace folder is open. If you see no Monk icon in the status bar and the chat window does not appear:
1

Make sure a folder is open — not a single file

2

Check that the Monk extension is installed and enabled in your IDE's extensions panel

3

Try reloading the window (Cmd+Shift+P → Reload Window)

If you are using a VS Code fork that is not listed on our Install Monk page, check that it supports the VS Code extension API. Most forks do, but some strip marketplace access.

​
Sign-In Problems

When you sign in, Monk opens a browser tab for authentication and redirects you back to the IDE. If the redirect 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
  • On Windows, make sure the IDE is registered as a URI handler — reinstalling the extension usually fixes this

​
Status Panel Shows Red or Yellow

The status panel is the first place to look. It highlights problems and tells you what to do.
1

Click the affected item to see details

2

Follow the instructions Monk provides

3

If it does not resolve, use the Report a Bug button

Report a Bug Common causes: missing system dependencies, network connectivity, file permission issues, or Docker daemon not running.

​
Agent Does Not See Monk (MCP Issues)

If your coding agent cannot find Monk after you enabled MCP: For IDE-embedded agents (Copilot, Cursor, Windsurf, Antigravity):
  • Confirm you ran Monk: Manage MCP Server → Enable MCP server in the command palette
  • Restart the IDE after enabling MCP — some agents only read config at startup
  • Check the agent’s MCP settings screen and verify Monk is listed and enabled
  • In Cursor, go to Tools & MCP settings. In VS Code, run MCP: List Servers
For standalone agents (Claude Code, Codex, Gemini CLI):
  • The IDE with Monk must be running with the same project open
  • Launch the standalone agent from the same project directory
  • Run /mcp (Claude Code, Codex) or gemini mcp list (Gemini CLI) to check
  • If Monk does not appear, try disabling and re-enabling MCP from the IDE

​
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: 
ask Monk to update my AWS credentials

​
Deployment Fails

If a deployment does not complete:
1

Ask your agent what went wrong

ask Monk what went wrong with the deployment
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:
  • Check the task board in Monk’s panel for progress details
  • Cloud provider API throttling can slow things down during peak hours
  • If it is stuck, ask Monk for status: ask Monk what is happening with the cluster
  • As a last resort, cancel and retry — Monk cleans up partial infrastructure automatically

​
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 in the chat window (Cmd+Shift+M / Ctrl+Shift+M). It has context about your environment and can often diagnose the problem faster than searching docs. If nothing helps, use the Report a Bug button — it collects environment details automatically and sends them to the engineering team.

Help & support

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