Troubleshoot
| Symptom | Cause | Fix |
|---|---|---|
| macOS asks “Do you want to change your default web browser to Chrome?” while tests run | The full Chrome app was started with a fresh profile | Install a headless Chrome build (npx @puppeteer/browsers install chrome-headless-shell@stable --path ~/.cache/puppeteer); the tests and headless captures use it first. Or set CHROME_BIN / NEXTJS_SCREENSHOTS_CHROMIUM to one. |
| A capture shot fails with “Navigation timeout of 60000 ms exceeded” | Transient; reruns pass | Rerun with --only <id>. |
| A capture shot fails on sign-in, loading, or the wrong workstream | The dedicated Chrome isn’t signed in, or shows another workstream | Fix the window, then rerun the shot. |
record-capture: “the report’s alt text differs from the inventory” | The record’s alt text changed after the brief was written | Regenerate the brief and capture again. |
transition: “is not allowed” | Records move one step at a time | Run prereqs --id <id> to see the next step and what it needs. |
trace: “annotated frame node ID is missing” | No annotated_node_id recorded | record-figma --id <id> --annotated-node-id <node>. |
figma-upload refuses a URL | The URL isn’t https on figma.com, or it expired (10 minutes) | Request fresh upload URLs and run it again. |
figma-export: “image host … refused” | Figma returned an image host the tool doesn’t allow yet | Confirm the host is Figma’s and add it to IMAGE_HOSTS in scripts/figma-export.mjs. |
| Apps Script: “Authorization required” keeps returning | Consent was given in another window or account | Click Review permissions in the same browser window and account, then Allow. |
| Apps Script: “Set the script property GITHUB_TOKEN” | The token wasn’t saved | Add it under Project Settings > Script properties, then Save script properties. |
dryRunSwap: not-found | The doc’s image has different alt text, or isn’t in the doc | Insert it once with the record’s alt text (first insert). |
dryRunSwap: checksum-mismatch | The manifest points at the wrong commit or file | Rebuild the manifest with the commit that holds the images. |
| The Content Publisher add-on shows Publish to a public site for a test doc | The doc is connected to the wrong collection | Connect it to a test collection before publishing. |
Known gaps are listed in known limitations.