Back to main page

Part 1: Build & Publish Your First Teaching App

0 of 13 complete
lesson

Troubleshooting and FAQ

Your app is built, it is on GitHub, and Vercel has given you a link. If any part of that did not go smoothly, this page is where you find out why.

♥

You are not doing it wrong

Every problem on this page is a normal one with a specific cause and a specific fix. None of them mean you have broken anything, and none of them can damage the app you built. Find the symptom that matches yours and work through it.

The most common problem: your app uses AI, and the live version does not

If your app asks an AI to do something while a student is using it — generating feedback, marking a written answer, producing an image — it works perfectly in AI Studio and then does nothing once it is live on Vercel. That is not a mistake you made. It is the expected behaviour, and the reason is worth understanding.

Why it happens

An app that calls Google's AI needs a key — a long password that tells Google which account the request belongs to. While you build inside AI Studio, Google quietly supplies one for you, so you never see it.

When you sync your project to GitHub, that key is deliberately left behind. This is a good thing: keys should never be sitting in a code repository. But it means your live app arrives on Vercel with no key, and its AI features have nothing to call. You usually see a blank space where the AI result should appear, or a message mentioning an API key.

Read this before you add a key

Adding your own key changes who pays. Inside AI Studio, Google covers the AI calls. Once your app is live with your key in it, every request your students make runs on your account and is billed to you. Free allowances exist, but they are limited, Google changes them, and a class working through an assignment can move through one quickly.

So the first question is not "how do I add a key?" It is "does this app actually need AI while students are using it?"

  • If no — a quiz, a calculator, a flashcard drill, a sorting exercise — you do not need a key, and you should not add one. The AI wrote the code; the finished app just runs it. Skip this whole section.
  • If yes — the AI feature is the point of the tool — then continue, and go in knowing you are turning on a meter.

There is a middle option worth considering: ask AI Studio to rebuild the feature without a live AI call. A set of pre-written feedback messages, or a fixed bank of questions, often teaches the same thing at no cost and with nothing to maintain.

If your app does need AI: adding the key

  1. Find out what your app calls the key. In AI Studio, ask: "What environment variable does this project read the Gemini API key from? Just tell me the name." It is usually GEMINI_API_KEY, but check rather than assume — the name has to match exactly, capital letters included.
  2. Create a key at aistudio.google.com/apikey. Copy it somewhere safe. Google will not show it to you again.
  3. In Vercel, open your project, then Settings → Environment Variables.
  4. Add a variable using the exact name from step 1, with your key as the value. Save it.
  5. Go to the Deployments tab and redeploy the most recent deployment. Adding a variable does not update a site that is already running — it has to be rebuilt.

Part 5 of this course covers keys, environment variables, and the safe way to use them properly. This is the short version to get you unstuck.

One thing to check while you are there

A key is only hidden if the part of your app that reads it runs on the hosting service — not in your students' browsers. Anything the browser reads, the visitor can read too, and that includes a key.

Ask AI Studio, with your project open:

"Does this project call the Gemini API from the browser or from server-side code? If it is from the browser, explain what it would take to move that call to the server. Do not print the value of any key."

If the answer is "from the browser", the feature will work — but treat that key as spendable by anyone who visits. Set a spending limit, keep the app link to people you trust, and replace the key when you are done. Moving the call to the server is the real fix, and it is exactly what Part 5 walks through.

Three rules for a key, from now on

  • Treat it like a password. Never paste it into your code, into a message to AI Studio, into a screenshot, or anywhere that reaches GitHub.
  • Set a spending limit and a usage alert in your Google account before you share the app widely. A public link with an AI feature behind it is a bill waiting to be run up.
  • If you think a key has been seen by anyone else, delete it at aistudio.google.com/apikey and create a new one — first, before anything else. That takes a minute and settles the problem completely. Part 5 covers the full version in What to do if a key leaks.

Other problems

Problem: your repository does not appear in Vercel's list

Why it happens: Either the sync from AI Studio has not finished, or Vercel is looking at a different GitHub account than the one AI Studio pushed to.
How to fix it: Open github.com and confirm the repository is actually there. If it is, check the account dropdown above Vercel's repository list and switch to the right account, or use the search box. If Vercel still cannot see it, use the option to configure or add a GitHub account and grant Vercel access to that repository.

Problem: the Vercel build failed

Why it happens: Something in the generated code does not survive being built outside AI Studio. This is a code problem, not a you problem.
How to fix it: Vercel shows a log of the failure. Copy the last twenty or so lines, paste them into AI Studio, and say: "My deployment failed with this error. Fix the project so it builds." Then sync to GitHub again — Vercel retries on its own.

Problem: the deploy succeeded, but the page is blank

Why it happens: The site built and shipped, but something fails the moment it runs in the browser — very often a missing key, as above.
How to fix it: First rule out the key. If your app has no AI features, describe the blank page to AI Studio, ask it to fix the project, and sync again. Also try a hard refresh — your browser may be showing you a cached copy of an earlier version.

Problem: you changed the app, but the live site looks the same

Why it happens: Changing the app in AI Studio does not change what is on GitHub. Vercel only knows about code that has been synced.
How to fix it: Sync to GitHub again, then watch the Deployments tab in Vercel — a new deployment should start within seconds. If your browser still shows the old version once it finishes, hard refresh the page.

Problem: AI Studio changed something you did not ask it to

Why it happens: A broad instruction gives the AI room to redesign things you were happy with.
How to fix it: Be explicit about what to protect: "Undo the change to the header. Keep everything else exactly as it is." Fix it in AI Studio before syncing — the version on GitHub is still your last good one until you push over it.

Questions people ask at this point

Is any of this going to cost me money?

Not for what Part 1 builds. AI Studio, GitHub, and Vercel all have free tiers that comfortably cover a classroom tool. The one thing that costs money is an app that calls AI while students use it — see the top of this page.

Can anyone find my app?

Your Vercel address is public to anyone who has the link, but it is not listed or advertised anywhere. In practice only the people you send it to will see it. If your app collects anything from students, that is a different conversation — check with your institution before you share it.

Can I take it down?

Yes, at any time. Delete the project in Vercel and the link stops working. Your code stays on GitHub, so nothing is lost and you can redeploy later.

Can I put it on my own web address?

Yes — the domain setup guide walks you from a .vercel.app address to something like mytool.myuniversity.ca.

Do I have to keep using AI Studio to make changes?

For now, yes, and it works fine. Part 3 shows you how to bring the project onto your own computer and edit it with an AI coding assistant, which is a far better experience once your app grows.

Still stuck?

Describe the situation to ChatGPT, Claude, or AI Studio itself. Specifics get you a useful answer far faster than "it does not work":

"I built a web app in Google AI Studio, synced it to GitHub, and deployed it on Vercel. Here is what I did: [your steps]. Here is what I am seeing: [exactly what appears on screen, including any error text]. What should I check next?"

One thing to leave out: never paste an API key into a chat message, a screenshot, or a support request.
Previous