Troubleshooting

Troubleshooting

Common problems with Geometry Playground and how to fix them. If your issue isn't here, please open a GitHub Issue with the details.

Problems are grouped into three categories:

• Swift Playground Book problems  ·  issues inside the Swift Playgrounds app
• Companion website problems  ·  issues on dbbudd.github.io
• Classroom workflow problems  ·  issues running the curriculum with students

---

Swift Playground Book problems

"The subscription link doesn't open Swift Playgrounds"

Cause: Safari on iPad needs to know that a URL starting with developer.apple.com/ul/sp0 should open Swift Playgrounds.

Fix:

1. Make sure Swift Playgrounds is installed (check the home screen, or search for it in Spotlight)
2. Open Safari, not Chrome or another browser. Only Safari honours the universal link convention Apple uses for playground subscriptions.
3. Tap and hold the link, then select Open rather than long-pressing for a preview
4. If Safari still doesn't offer to open in Swift Playgrounds, open Swift Playgrounds first, then tap the link again

As a fallback, use the manual subscription method described in Setup#2-subscribing-to-the-swift-playground-book.

"The Geometry book doesn't appear in my library"

Cause: The subscription was added but the book hasn't downloaded yet.

Fix: In Swift Playgrounds, tap See All near the top of the library, scroll to the Subscriptions section, and tap Get next to Geometry. The download is a few megabytes and should complete in seconds.

If the subscription isn't even listed under Subscriptions, re-run the one-click link from Setup.

"My student's code won't run, it just shows a red error"

Common causes and fixes:

Mismatched parentheses or braces. Swift Playgrounds shows a red indicator on the line where the error was detected, which is often slightly after the line with the actual problem. Have the student count opening ( { and closing ) } in the code directly above the red mark.

Missing addShape(pen: p). The pen holds instructions in memory but nothing draws until addShape is called. A common mistake is to have the code running but without this final line.

Wrong variable name. Swift is case sensitive. Pen is the type, pen is a common variable name, and p is the convention used in the curriculum. p.addLine and pen.addLine will both work as long as you named the variable consistently.

Using semicolons. Swift doesn't need semicolons. They are tolerated but break on some combinations. The curriculum style is "one command per line, no semicolons".

Accidentally editing the template code around the student section. If the student modified text outside the clearly marked student area, the playground may refuse to compile. Reset the page by tapping the Reset icon in the top toolbar.

"The canvas is blank but the code ran without errors"

Cause: The pen moved but didn't draw anything visible. Common reasons:

• p.move(distance: 100) was used instead of p.addLine(distance: 100). move repositions the pen without drawing a line.
• The shape was drawn but ended up off-screen (for example, p.goto(x: 1000, y: 1000) puts the pen outside the visible canvas).
• addShape(pen: p) was never called.
• All the addLine distances were zero.

"My playground crashes or freezes"

Fix:

1. Force-quit Swift Playgrounds (swipe up from the bottom of the screen and swipe the app away)
2. Reopen the app
3. If the crash keeps happening on the same page, use Reset Page from the page menu

If a specific chapter consistently crashes the app, please open a GitHub Issue with the chapter and section name, the iPad model, and the iPadOS version.

"I can't see the Show Solution button"

The solution reveal is on the companion website, not inside the Swift Playgrounds app itself. Open the relevant chapter on dbbudd.github.io, scroll to the exercise, and tap the Show Solution button at the bottom of the exercise description.

---

Companion website problems

"The vocabulary popovers aren't appearing"

Cause: The dashed underline on vocabulary terms appears when the word first occurs in each chapter. If you are looking at a later occurrence of the same word, it will stay as plain text.

Fix: Scroll back up in the chapter to find the first occurrence of the term. It should have the dashed cyan underline. Hover over it (on desktop) or tap it (on mobile) to see the definition.

Bold text that matches a vocabulary term will also show a popover, regardless of position in the chapter.

"Search returns no results or only results from the current page"

Cause: You may be running the site locally via file:// protocol (for example, by double-clicking a saved HTML file), which blocks cross-file search.

Fix: Open the site via its real URL at dbbudd.github.io. Site wide search requires HTTPS.

If this happens on the live site itself, open the browser developer console and look for a message starting with [course-ui]. It will tell you how many pages were indexed. Paste the message into a GitHub Issue.

"The site looks broken on my phone"

Cause: Browser cache holding an old version of the stylesheet.

Fix:

• iOS Safari: Settings > Safari > Clear History and Website Data
• Chrome / Firefox: Open the site, pull down to refresh, or use incognito / private mode

The site is fully responsive and tested on phones down to 320 pixels wide. If it still looks broken after a cache clear, please report with a screenshot and your phone model / browser.

"Dark mode doesn't match my system"

Cause: The theme was manually overridden on a previous visit.

Fix: Tap the Aa button in the top bar and select the theme that matches your system preference. The choice is remembered in browser local storage.

To reset to "follow system", clear the site data for dbbudd.github.io in your browser settings.

"The site doesn't load at all"

Possible causes:

• Your school's content filter is blocking dbbudd.github.io or raw.githubusercontent.com. Ask your IT team to allowlist these domains.
• GitHub Pages is having an outage. Check githubstatus.com.
• Your internet connection is down. Open another website to confirm.

---

Classroom workflow problems

"Students are racing ahead and getting lost"

Cause: Swift Playgrounds lets students skip ahead freely. Motivated students can jump to Chapter III before they have internalised Chapter I's foundations, then struggle because they missed the walking metaphor for angles.

Fix:

• Lock the pacing by telling students "Chapter I must be completed before anyone starts Chapter II". Enforce via classroom management, not technology.
• Use the per-section Mark as Complete button on the companion website. Students self-track and you can spot-check.
• Treat the first lesson on Chapter II as a brief review of Chapter I's key idea (sum of exterior angles = 360 degrees) to catch students who skipped.

"Students have finished the whole chapter in half the time I expected"

Cause: Bright students with prior coding experience move through the straightforward exercises quickly.

Fix: Use the extension suggestions at the end of each chapter (the "Coming Up" preview sections often reference harder variants). Challenge them to:

• Rewrite an earlier chapter's exercise using only the new chapter's techniques
• Extend a shape to 3D style perspective (fake it with two layered shapes)
• Write a "create a pattern with N copies" version using a loop
• Compose several exercises into one bigger visual piece

"Some students can't get their iPad to run the code at all"

Work through this checklist with the student:

1. Is Swift Playgrounds installed? (Check for the icon on the home screen.)
2. Is the Geometry book in the library? If not, re-run the subscription link.
3. Is their iPad running iPadOS 15 or later? Go to Settings > General > About.
4. Does any other Swift Playgrounds book work? (If Learn to Code 1 also fails, the problem is with Swift Playgrounds itself, not Geometry.)
5. Have they tried the Reset button on the exercise page?

If all of those pass but the code still won't run, the iPad may need a full app reinstall (delete Swift Playgrounds, reinstall from the App Store, re-subscribe to Geometry).

"A student asked a question I can't answer"

This happens more often in the later chapters where students get creative. Some survival tactics:

• "Great question, let's find out together." Model the problem-solving process live on the projector.
• Search the companion site. ⌘K opens site wide search; type the concept name and see what the curriculum says about it.
• Check the vocabulary popover. Over 70 maths and coding terms have definitions a single hover or tap away.
• Post the question in a GitHub Issue. Tag it as "teaching question" and I'll respond.

A "Teaching FAQ" page is planned for this wiki to collect the most common student questions and pedagogical responses over time.

---

Still stuck?

Open a GitHub Issue with:

1. What you were trying to do (one sentence)
2. What actually happened (one sentence)
3. Chapter and section (if applicable)
4. Device details (iPad model, iPadOS version, Swift Playgrounds version)
5. Screenshot (if it's a visual problem)

I respond to issues within a few days.