Troubleshooting

Authentication

"401 Unauthorized" on every command

Your token may be expired or revoked. Re-authenticate:

mog auth

Or check your current status:

mog auth --status

If you're using MOG_TOKEN in an environment variable, verify it's set and valid:

echo $MOG_TOKEN

Device code flow times out

The device code expires after 15 minutes. If you didn't approve in time, run mog auth again to get a fresh code.

If you're behind a corporate proxy or firewall that blocks mog.md, the polling may fail silently. Check your network and try again.

"403 Forbidden — insufficient scope"

Your token doesn't have the required scope for the operation. Common mismatches:

Operation	Required scope
mog search, mog ls	read
mog buy, mog install --auto-buy	purchase
mog install (download step)	download
mog publish, vendor operations	sell

Generate a new token with the right scopes from Dashboard → Settings.

Installation

"Package not found"

Check the exact coordinates (case-sensitive, vendor/slug format):

mog search "package name"

Verify the vendor and slug match what's listed on mog.md.

"Target not detected"

The CLI auto-detects your editor by looking for marker directories (.cursor/, .claude/, .windsurf/, .gemini/, .codex/, .openclaw/). If none are found, it falls back to generic.

To fix, either create the marker directory or specify the target explicitly:

mog install acme/my-skill --target cursor

Installed files are in the wrong location

Check which target was auto-detected:

mog ls --json

Look at the target and installPath fields. If they're wrong, uninstall and reinstall with --target:

mog uninstall acme/my-skill
mog install acme/my-skill --target cursor

"SHA-256 mismatch"

The downloaded archive doesn't match the hash recorded on the server. This could indicate a corrupted download or a tampered package. Try again:

mog uninstall acme/my-skill
mog install acme/my-skill

If the error persists, report the package to support@mog.md.

MCP servers

MCP server not showing up in my editor

After installing an MCP server with mog, you must restart your editor for it to discover the new config. This applies to all editors — Cursor, Claude Code, Gemini CLI, Windsurf, and Codex.

"Config file not found" during MCP install

The CLI needs the target config file to exist (or its parent directory). For Cursor, ensure .cursor/ exists. For Codex, ensure .codex/ exists. Running mog init creates the necessary scaffolding.

MCP server starts but tools aren't available

Check that the server's dependencies are installed. For npx-based servers, ensure Node.js is on your PATH. For Python servers (uvx, python3), ensure the Python environment is set up.

Test the server manually:

npx -y @acme/github-mcp-server@1.0.0

If it crashes, the issue is with the server package, not mog.

Environment variables not being passed

Verify the env vars are in the MCP config file. For Cursor, check .cursor/mcp.json. For Codex, check .codex/config.toml. If you installed non-interactively, make sure you passed all required env vars with --env.

Purchases & billing

"402 — approval required"

Your spend policy blocked the purchase. The response includes an approvalUrl:

{
  "status": "approval_required",
  "approvalUrl": "https://mog.md/purchases/approve?listing=uuid",
  "reason": "Price (1500¢) exceeds your policy limit (1000¢)"
}

Either:

• Visit the approvalUrl to approve manually
• Ask your org admin to increase the spend policy limit
• Use a token without a spend policy (personal use only)

"402 — insufficient balance"

Your wallet balance is too low. Top up:

1. Go to Dashboard → Billing
2. Add funds to your wallet
3. Retry the purchase

Or enable auto top-up so this doesn't happen again. See Wallet & billing.

Purchase succeeded but package didn't install

The purchase and install are separate steps. If mog buy succeeded but mog install failed, your entitlement is saved — you won't be charged again. Run mog install to retry the download and extraction.

Lockfile

"Lockfile integrity check failed"

mog doctor reports that installed files don't match the lockfile hashes. This can happen if files were manually edited or corrupted.

Reinstall to restore integrity:

mog uninstall acme/my-skill
mog install acme/my-skill

Merge conflicts in mog.lock.json

After resolving git merge conflicts, run mog install to ensure the lockfile and installed packages are consistent. The CLI reconciles any mismatches.

"Lockfile not found"

Run mog init to create the lockfile:

mog init

Then run mog install for each package you need.

Wiring

Skill installed but agent doesn't use it

Installing a skill extracts files, but your editor's AI still needs to be told about them. Use --wire to create the appropriate config:

mog install acme/my-skill --wire

For Cursor, this creates a .cursor/rules/<slug>.mdc file. For Claude Code, it appends to AGENTS.md. Without wiring, the skill sits in the directory but isn't referenced.

"Wire already exists"

If you reinstall with --wire and a rule/reference already exists, the CLI skips the wiring step to avoid duplicates. To force a rewire, delete the existing rule file and reinstall with --wire.

Updates

"No updates available" but the listing page shows a newer version

Check which update channel you're on. By default, mog update only applies patch and minor updates. If the new version is a major bump, you need to install it explicitly:

mog install acme/my-skill@2.0.0

Update breaks something

Roll back by installing the previous version explicitly:

mog install acme/my-skill@1.2.0

The lockfile records the exact version, so you can always restore a known-good state.

Still stuck?

Run the full diagnostic:

mog doctor --json

This checks authentication, lockfile integrity, package hashes, wiring, and MCP config in one pass. If the issue isn't covered here, reach out at support@mog.md with the mog doctor --json output.