When something goes wrong, moodle-cli prints an error name (like auth) and a hint telling you what to do. This page lists what you might see and how to fix it. Scripting this? See Moodle CLI for scripts and agents for the full error and exit-code reference.

​
Error codes

submit, uninstall, auth login, auth keepalive install/auth keepalive uninstall, and the mcp deployment commands all mutate state and go through the same plan-confirm flow; see Mutations for the full list.

​
ambiguous — a reference matched more than one thing

A UNIT, section or item phrase that matches more than one record fails and lists every match, instead of guessing. See How ambiguity resolves for the interactive picker moodle-cli shows at a terminal. Fix: use one of the listed candidates, or narrow the phrase until only one thing matches. Symptom: moodle doctor’s browser check reports fail, or an auth error’s hint mentions Full Disk Access. Cause: Full Disk Access is granted to your terminal application, never to the CLI process itself, and a sandboxed terminal (an IDE’s integrated terminal, an agent runner) usually can’t be granted it at all. See macOS Full Disk Access and cookie stores for which cookie stores this affects and why. Fix: grant Full Disk Access to the terminal app named in the hint, then fully restart that app — not just the tab:
Or skip the store entirely:

​
Expired session

Symptom: a command that worked yesterday now fails with auth, or moodle auth status reports session_alive: false. Fix: re-authenticate:
If you rely on a deployed MCP (Model Context Protocol) server rather than the local CLI, its session expires independently of your terminal’s saved one; moodle mcp login sends it a fresh session. See Connect an agent for that flow.

​
Keepalive not running

Symptom: sessions keep expiring even though you installed keepalive. Check:
A job check failing in moodle doctor means the background job can no longer read browser cookies (for example, after switching Node versions) or its runtime no longer exists. Reinstall it:
On Linux there’s no job to check — keepalive only runs if you scheduled the cron line yourself; see Keepalive.

​
Cloudflare deployment problems

Deployment and remote-session issues for the managed MCP server (Cloudflare sign-in, Worker deploy failures, OAuth pairing) are specific to that surface and covered in Connect an agent and MCP troubleshooting. moodle mcp status --verbose and moodle doctor’s mcp check are the starting points; moodle mcp deploy --repair is the general-purpose fix for a deployment stuck in a bad state.

​
What moodle doctor checks mean

moodle doctor runs the checks documented in Sign in: sqlite, config, session, browser, one job per background job you have running, and mcp. Only sqlite, config and browser can report fail; session, job and mcp only ever report pass or warn.