Troubleshooting

Run /doctor

Start here. /doctor in the shell checks each piece of your setup in order and suggests a fix for anything that fails:

1. Whether a Canvas address is configured, and whether it came from the environment or your profile
2. Whether a token is present
3. Whether the token looks like a Canvas token, catching stray spaces, quotes, and placeholder text
4. A live request to Canvas as you, with the response time
5. Your AI provider and model
6. The provider itself: for Anthropic, OpenAI, and Google, a real request to check the key; for Copilot and Codex, whether the CLI is installed, and for Codex whether it is signed in. Bedrock credentials are not checked

Outside the shell, canvas-cli status shows what is configured without connecting to anything.

Sign-In Errors

“Invalid access token” or 401

• The token expired. If you set an expiry date when you made it, it has passed; some schools also expire tokens by policy. Make a new one under Account → Settings → Approved Integrations and run canvas-cli login.
• The token was deleted in Canvas, or your school revoked it. Check that it still appears under Approved Integrations.
• It was pasted with extra characters. /doctor flags spaces and quotes around it.

“Canvas API not found at this URL” or 404

The address is not your school’s Canvas. Use the address you see in the browser when you are signed in, such as school.instructure.com or canvas.school.edu, without any path. If you set CANVAS_BASE_URL yourself, it must end in /api/v1.

A redirect, or a sign-in page

Some schools put Canvas behind single sign-on. /doctor reports a redirect when that happens; try the address your browser lands on after signing in. During canvas-cli login the same problem can show up as a “Connection failed” message instead.

No “New Access Token” button

Your school has turned off personal tokens for students. canvas-cli cannot work without one; ask your Canvas administrators whether they can be enabled.

Network Errors

• A VPN may be required. Many schools only allow Canvas API access from their network.
• A firewall may be blocking it. Campus and workplace networks sometimes block API traffic; try another network.
• Check the connection directly, replacing the address and token with yours:

curl -H "Authorization: Bearer YOUR_TOKEN" https://school.instructure.com/api/v1/users/self

If that returns your name as JSON, Canvas is reachable and the token works, and the problem is in canvas-cli’s configuration; canvas-cli status shows what it is using. Rate limits and server errors are retried automatically, up to three times, before canvas-cli gives up.

Missing Courses

• Only current courses are listed. canvas-cli hides courses that have concluded, that you are no longer active in, or whose term ended more than 30 days ago.
• Your course list is per folder. Starting canvas-cli in a new folder asks you to pick courses again. Use /manage-courses to add one you skipped.
• The course is not published yet. Canvas hides unpublished courses from students until the instructor publishes them.
• A course shows as unavailable. It is in your list but Canvas no longer returns it. Remove it with /manage-courses.

If files or pages are missing from a course, your school may block those parts of the API for students; see Blocked APIs. Run /refresh in the course after your instructor posts something new.

AI Not Working

• “AI is unavailable because no provider key is configured”. Run canvas-cli login or /model and choose a provider. Setting a provider without its key also leaves AI off.
• The key is rejected. Check it has not been revoked, and that the account has credit. /model key replaces it.
• Rate limited. Wait a minute and try again, or switch to a model with higher limits.
• Copilot or Codex. /doctor checks that the CLI is installed, and for Codex that it is signed in; Copilot’s sign-in is only checked on first use. Install it with npm install -g @github/copilot or npm install -g @openai/codex, then run copilot login or codex login.
• “The request is too large for GitHub Copilot”. Start over with /clear, or ask about fewer documents at once.
• Thin answers. The assistant only knows what has been downloaded. Run /refresh in the course, and ask in a workspace for assignment details.

Install Problems

“command not found: canvas-cli”

The install folder is not on your PATH. For the install script it is ~/.local/bin; add it to your shell’s startup file and open a new terminal. For zsh (for bash or fish, use the line the installer printed):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

An old version keeps running

You probably have two installs, one from npm and one from the script. which -a canvas-cli lists them in the order your shell finds them; remove the one you do not want.

“canvas-cli requires Node.js 20.10 or later”

The npm package needs Node.js 20.10 or newer. Update Node, or use the install script, which needs no Node.js at all.

Copying does nothing on Linux

/copy needs a clipboard tool: install wl-clipboard on Wayland, or xclip or xsel on X11.

Starting Over

• /clear resets the conversation in the current scope.
• /refresh re-downloads a course, or rebuilds a workspace.
• canvas-cli login replaces your sign-in; canvas-cli logout removes it.
• canvas-cli clean deletes all course data, workspaces (including your notes and work/folders), conversations, and exports in this folder; clean --all removes your sign-in too.