Alan Gandy

Common issues, validation failures, and where to ask for help.

Troubleshooting

A reference catalogue of the most common error messages you'll see during validation, deploy, and post-push verification — grouped by tier, with the actual cause of each and the fastest fix.

Common validation failures and what they mean

Generation and validation each take 1–3 minutes. Browser notifications let you start a job, switch tabs, and get pinged when it's done. This article shows where the toggle is, when notifications fire, and how to debug them when they don't.

Browser notifications

When the Help Center doesn't have your answer, the chat widget on every page reaches us directly. This article shows where the widget lives, what response times to expect, and how to write a support message that gets a fast useful reply.

Getting help — the chat widget

Pushing your assignment to GitHub and turning it into a Classroom assignment students can join.

Deploying to GitHub Classroom

After validation passes, the Continue to Deploy button unlocks. This article walks through the Deploy step — picking your GitHub organization, choosing a repository name, what happens during the push, and what to do when it fails.

Deploying your assignment

After deploy succeeds and post-push validation passes, the Classroom setup guide unlocks. This article walks the GitHub Classroom new-assignment wizard end-to-end with every value pre-filled, including the critical protected-paths list and why you should NOT configure Classroom's own autograder.

Setting up your GitHub Classroom assignment

After deploy succeeds, CodeTeach watches the real GitHub Actions run and shows one of three banner states — pending, passed, or failed. This article explains what each state means and what to do, especially when real GHA fails after CodeTeach's replica passed.

Reading the post-push validation banner

The Download ZIP button on the Deploy step packages your validated assignment as a ready-to-deploy zip file. This article explains what's inside, when to use it instead of automated GitHub deploy, and how to deploy manually from the ZIP.

Downloading the assignment ZIP

Editing the AI's output, approving instructions, and running the autograder check.

Reviewing & Validating

After generation, your assignment lands here for review. Four tabs (Starter / Solution / Tests / Instructions), an in-browser code editor, and the approval gate that unlocks the autograder check. This is where you catch issues before they reach students.

The Review & Edit screen

The Tests tab on Review & Edit is where you shape what the autograder grades. The AI gives you a starting set; this article covers adding, editing, reordering, and deleting tests, plus the three comparison types and how to catch common bugs.

Editing tests

When you open the Instructions tab, a yellow banner blocks the autograder check until you approve. This article explains why the gate exists and what to actually check during review — including the difficulty-fit check that catches the most common AI mismatch.

Approving instructions — the approval gate

After approving instructions, you click Run autograder check. This article walks through the two validation tiers (sandbox + replica), what passes and fails mean, why we require 100%, and why we removed the AI auto-fixer.

The autograder check

Validation failed and you're back on Review & Edit looking at a bounce-back banner. This article walks through reading the failure summary, deciding between manual edits and the AI Wizard, the most common failure modes, and how to re-validate.

When validation fails — fixing it

The four ways to generate an assignment, and how to choose the right difficulty level.

Creating Assignments

Your first decision when creating an assignment. Four modes, picked by what you have on hand — existing code, prose, or both. The right mode keeps generation fast and predictable; the wrong one wastes credits.

Picking a generation mode

How to use Forward mode when you already have a starter file with TODO markers. Most predictable of the four modes; the AI fills in solution, tests, and instructions while preserving your starter's structure.

Forward mode — start from your starter code

How to use Backward mode when you already wrote the answer and want the AI to strip it into a fill-in-the-blanks lab. Best for converting your own reference implementation into student work.

Backward mode — start from your working solution

Highest-control generation mode. You provide both the starter and the solution; the AI handles only the tests and instructions. Best when you've already prepared a lab manually and just want the autograder built.

Both Provided mode — when you have starter and solution

Highest-leverage generation mode. You provide prose (a lab description, syllabus excerpt, or chapter problem); the AI builds starter, solution, tests, instructions, and workflow from scratch. Best for digitizing old paper labs or quickly turning a textbook problem into graded work.

From Document mode — convert a lab handout into an assignment

The most consequential setting in the wizard. Difficulty isn't just about code complexity — it directly controls how much working code appears in the student-facing Instructions.md. Beginner shows the answer; Advanced gives only requirements. Pick deliberately.

Choosing a difficulty level (Beginner / Intermediate / Advanced)

How CodeTeach handles external libraries — what auto-installs without configuration, when you need to configure something manually, and the full walkthrough for adding a library that the auto-installer doesn't know about yet.

Adding external libraries to your assignment

What CodeTeach.ai does, how to set it up, and a tour of your dashboard.

Getting Started

First time here? In 10 minutes you can have your first AI-generated assignment deployed to your GitHub Classroom. This article shows you what to expect and where to go next.

Welcome to CodeTeach.ai

Walks through the three GitHub-side prerequisites — organization, CodeTeach App, Classroom — that you need to deploy your first assignment. Most "deploy failed" frustration comes from missing one of these; do them in order and you'll skip every common gotcha.

Setting up GitHub for CodeTeach

A walkthrough of the dashboard — what every column, status badge, and sidebar item means. Read this once and you'll always know what state your assignments are in and where to click to take the next action.