# Common Issues and Solutions

Quick fixes for the most common problems with Canvas MCP.

## Installation Issues

### "canvas-mcp-server: command not found"

**Problem**: The CLI command isn't available after installation.

**Solution**:
```bash
# Make sure you installed with the editable flag
uv pip install -e .

# Or reinstall
pip uninstall canvas-mcp
uv pip install -e .

# Verify it worked
canvas-mcp-server --help
```

### "No module named 'canvas_mcp'"

**Problem**: Package not installed correctly.

**Solution**:
```bash
# Navigate to the canvas-mcp directory
cd /path/to/canvas-mcp

# Install in editable mode
uv pip install -e .
```

## Configuration Issues

### "Authentication failed"

**Problem**: Canvas API token is invalid or expired.

**Solution**:
1. Go to Canvas → Account → Settings
2. Scroll to "Approved Integrations"
3. Delete the old token if present
4. Create a new access token
5. Update your `.env` file with the new token
6. Restart your MCP client

### "Canvas API URL is invalid"

**Problem**: Wrong URL format in `.env`.

**Solution**:
Your Canvas API URL should look like:
```bash
CANVAS_API_URL=https://canvas.illinois.edu
```

**NOT**:
- ❌ `https://canvas.illinois.edu/` (no trailing slash)
- ❌ `https://canvas.illinois.edu/api/v1` (don't include /api/v1)
- ❌ `canvas.illinois.edu` (must include https://)

Test with:
```bash
canvas-mcp-server --test
```

### "Cannot create access token" (Students)

**Problem**: Your institution restricts student API access.

**Solution**:
Contact your Canvas administrator or IT help desk:
```
Hi, I'm trying to use the Canvas API to track my assignments
and grades. Could you help me create an API access token or
enable API access for my account?
```

Most institutions will enable this for legitimate educational purposes.

## Runtime Issues

### "Rate limit exceeded (429 errors)"

**Problem**: Making too many API requests too quickly.

**Good news**: Canvas MCP now automatically handles rate limiting!

**What happens**:
- Canvas MCP detects rate limit errors
- Automatically waits and retries (up to 3 times)
- Shows progress: "⏳ Rate limited (429). Retrying in 4s..."

**If it still fails**:
- Wait a few minutes before trying again
- For bulk operations, the code execution API is more efficient

### "Tool not showing up in Claude Desktop"

**Problem**: Canvas MCP tools aren't available in Claude.

**Solution**:

1. **Check your MCP client's configuration file**:
   
   **Claude Desktop** (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
   **Claude Desktop** (Windows): `%APPDATA%\Claude\claude_desktop_config.json`
   **Cursor** (macOS/Linux): `~/.cursor/mcp_config.json`
   **Windsurf** (macOS): `~/Library/Application Support/Windsurf/mcp_config.json`
   **Zed**: Settings → Open Settings (`settings.json`)
   
   Ensure it contains:
   ```json
   {
     "mcpServers": {
       "canvas-api": {
         "command": "canvas-mcp-server"
       }
     }
   }
   ```
   
   Or for Zed:
   ```json
   {
     "context_servers": {
       "canvas-api": {
         "command": {
           "path": "/absolute/path/to/canvas-mcp-server",
           "args": []
         }
       }
     }
   }
   ```

2. **Restart your MCP client completely**:
   - Quit the application (not just close the window)
   - Reopen it

3. **Check for errors**:
   - For Claude Desktop: Look in the developer console
   - For other clients: Check client logs or developer console
   - Or run manually: `canvas-mcp-server` and check for errors

### "Data seems outdated"

**Problem**: Seeing old information.

**Solution**:
Canvas MCP caches some data for performance. The cache TTL is set in your `.env`:

```bash
CACHE_TTL=300  # 5 minutes (default)
```

To see fresh data immediately:
- Restart the MCP server (restart your MCP client)
- Or wait for cache to expire (default: 5 minutes)

## Data Issues

### "Student names showing as Student_xxxxxxxx"

**This is working correctly!** If you have anonymization enabled:

```bash
ENABLE_DATA_ANONYMIZATION=true
```

This is for FERPA compliance. Student data is anonymized before reaching Claude.

**To disable** (only if you don't need FERPA compliance):
```bash
ENABLE_DATA_ANONYMIZATION=false
```

Then restart your MCP client.

### "Missing some courses or assignments"

**Problem**: Not all data is showing up.

**Possible causes**:

1. **Canvas permissions**: Your API token might not have access to all courses
   - Solution: Check your Canvas role and permissions

2. **Archived courses**: Old courses might be archived
   - Solution: Unarchive in Canvas if needed

3. **Pagination issue**: Very large datasets might not load completely
   - Solution: Be more specific (e.g., "Show assignments in CS 101" instead of "Show all assignments")

## Performance Issues

### "Bulk operations are very slow"

**Problem**: Grading or analyzing large datasets takes too long.

**Solution**: Use the code execution API for bulk operations:

Instead of:
```
Show me all 90 student submissions and grade them
```

Use:
```
Use the bulk grading code API to grade all submissions for Assignment 5
```

This is **99.7% more efficient** for large datasets!

### "AI assistant seems to get confused with lots of data"

**Problem**: Too much data in context.

**Solution**:
- Be specific about what you want
- Use filters (course names, assignment IDs, date ranges)
- For large operations, use code execution to keep data out of your AI assistant's context

Example:
```
Show me students who haven't submitted Assignment 3 in CS 101
```
Instead of:
```
Show me all students and all their submissions
```

## Integration Issues

### "Works in terminal but not in MCP client"

**Problem**: `canvas-mcp-server` works manually but not through your MCP client.

**Solution**:

1. **Check the command path**:
   ```bash
   which canvas-mcp-server
   ```

2. **Use full path in config** if needed:
   
   For Claude Desktop, Cursor, Windsurf, Continue:
   ```json
   {
     "mcpServers": {
       "canvas-api": {
         "command": "/full/path/to/canvas-mcp-server"
       }
     }
   }
   ```
   
   For Zed:
   ```json
   {
     "context_servers": {
       "canvas-api": {
         "command": {
           "path": "/full/path/to/canvas-mcp-server",
           "args": []
         }
       }
     }
   }
   ```

3. **Check environment variables**: Your MCP client might not have access to your `.env`
   - Make sure `.env` is in the canvas-mcp directory
   - Or set `CANVAS_API_TOKEN` and `CANVAS_API_URL` as system environment variables

## Getting More Help

1. **Enable debug mode** in your `.env`:
   ```bash
   DEBUG=true
   LOG_API_REQUESTS=true
   ```

2. **Test the connection**:
   ```bash
   canvas-mcp-server --test
   ```

3. **Check the logs**: Run the server manually to see error messages

4. **Still stuck?**
   - [Open an issue](https://github.com/vishalsachdev/canvas-mcp/issues)
   - Include:
     - Error messages (redact your API token!)
     - Your Canvas instance type (e.g., "canvas.illinois.edu")
     - What you were trying to do
     - Output from `canvas-mcp-server --test`

## Quick Diagnostic Checklist

Run through this list:

- [ ] `.env` file exists and has `CANVAS_API_TOKEN` and `CANVAS_API_URL`
- [ ] Canvas API token is valid (test in Canvas web UI)
- [ ] `canvas-mcp-server --test` succeeds
- [ ] Claude Desktop config includes canvas-mcp
- [ ] Restarted Claude Desktop after config changes
- [ ] Canvas API URL doesn't have trailing slash or /api/v1

If all these pass and it still doesn't work, [open an issue](https://github.com/vishalsachdev/canvas-mcp/issues)!
