Common Issues

Solutions to frequently encountered problems.

Submission Issues

"No valid Gradescope session"

Cause: The server's Gradescope TOKEN or COOKIE has expired.

Solution:

1. Log into Gradescope as an instructor
2. Get fresh credentials (see Environment Configuration)
3. Update .env file
4. Restart the server:

pm2 restart gradescope-submitter

"Missing required fields"

Cause: Assignment parameters not passed correctly in the URL.

Solution:

1. Check the iframe URL has asg_id parameter
2. Verify the assignment ID exists in Gradescope
3. Ensure the URL format is correct:

?asg_id=6617143&file_name=program.py

"Submission failed"

Cause: Network error or Gradescope API issue.

Solution:

1. Check server logs: pm2 logs
2. Verify internet connectivity
3. Try again after a few minutes
4. Check Gradescope status page

Code Execution Issues

"Python interpreter failed to load"

Cause: Pyodide (Python runtime) failed to download.

Solution:

1. Check internet connection
2. Refresh the page
3. Wait for "Loading Python..." to complete
4. Try a different browser

Code runs forever / hangs

Cause: Infinite loop in your code.

Solution:

1. Refresh the page to stop execution
2. Check your loop conditions:

# Bad - infinite loop
while True:
    print("forever")

# Good - has exit condition
while count < 10:
    print(count)
    count += 1

"NameError: name 'X' is not defined"

Cause: Typo in variable/function name, or variable not defined yet.

Solution:

1. Check spelling
2. Ensure variable is defined before use
3. Check indentation (variable might be in wrong scope)

D2L / Iframe Issues

Iframe not loading

Cause: HTTPS/SSL issues or X-Frame-Options blocking.

Solution:

1. Ensure server has valid HTTPS certificate
2. Check that your domain allows iframe embedding
3. Verify D2L whitelist includes your domain
4. Check browser console for specific errors

Iframe shows blank page

Cause: JavaScript error or failed resource load.

Solution:

1. Open browser Developer Tools (F12)
2. Check Console tab for errors
3. Check Network tab for failed requests
4. Verify all CDN resources are accessible

"Refused to display in a frame"

Cause: X-Frame-Options header blocking embedding.

Solution:

Check your server isn't sending restrictive headers:

// In app.js, ensure you're NOT sending:
// res.setHeader('X-Frame-Options', 'DENY')

Authentication Issues

"Invalid LTI launch"

Cause: LTI configuration mismatch.

Solution:

1. Verify LTI_CLIENT_ID matches D2L registration
2. Verify LTI_DEPLOYMENT_ID matches D2L registration
3. Check server logs for specific validation errors
4. Ensure HTTPS is properly configured

Student not recognized

Cause: Email mismatch between D2L and Gradescope.

Solution:

1. Check student's email in D2L
2. Verify same email is enrolled in Gradescope
3. LTI passes email from D2L automatically

Server Issues

Server won't start

Cause: Missing dependencies or configuration.

Solution:

1. Run npm install
2. Check .env file exists and has required variables
3. Check for port conflicts:

lsof -i :3000

"EADDRINUSE: address already in use"

Cause: Another process is using port 3000.

Solution:

# Find the process
lsof -i :3000

# Kill it
kill -9 <PID>

# Or use a different port in .env
PORT=3001

Server crashes on startup

Cause: Syntax error or missing module.

Solution:

1. Check the error message
2. Run npm install to ensure all dependencies
3. Check for syntax errors in app.js

Browser Issues

Editor not displaying correctly

Cause: CSS not loading or browser compatibility.

Solution:

1. Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
2. Clear browser cache
3. Try a different browser (Chrome recommended)

Can't type in editor

Cause: JavaScript error preventing CodeMirror initialization.

Solution:

1. Check browser console for errors
2. Refresh the page
3. Disable browser extensions that might interfere

Getting More Help

If none of these solutions work:

1. Check server logs: pm2 logs gradescope-submitter
2. Enable debug mode in .env: DEBUG=true
3. Open an issue on GitHub