# Troubleshooting

Find the likely cause and the next action for a blocked workflow.

## Repository missing from Setup
Check that the Framecheck GitHub App is installed on the correct personal account or organisation and has access to that repository. Ask an organisation owner to approve a pending installation or permission update. Sign in to the intended GitHub account before reconnecting.

## Upload token missing or refused
Verify the secret name `FRAMECHECK_TOKEN`, project ID, and token provenance. Dependabot has a separate secret store; fork pull requests do not receive repository secrets. Run precheck before rebuilding. See [tokens](/tokens/).

## Storybook build cannot be found
Check the command's working directory and `--storybook-dir`. Confirm the build succeeded and the directory contains the static Storybook files, including its story index. A source checkout or empty output folder is not an uploadable build.

## Run queued
A queued upload was accepted but has not started capture. Runs share capacity. Check the run's status, billing notices, and [system status](https://status.framecheck.dev). Repeatedly uploading the same commit is not a way to speed up the queue.

## Story timed out or is blank
Open the static build locally. Check missing assets, blocked hosts, unresolved requests, loaders, and play functions. Make the story settle with predictable fixtures. Consider a higher story timeout only after fixing the cause; reduce parallel pages if the stories are unusually resource-heavy.

## Fonts, images, or API data missing
Bundle the assets or add the intended public host to the external allowlist. Check the run's diagnostics for blocked requests. Your laptop's cookies, credentials, and private services are not available during hosted capture.

## Viewport not found
Define the named viewport in Storybook's viewport configuration or use explicit `framecheck.viewport` dimensions. For Storybook 9+, use the current viewport globals rather than relying on legacy `defaultViewport`. Run again after correcting it.

## Every story appears new
The project may not yet have an accepted baseline, or the story IDs, modes, browser, or capture settings changed. Check the baseline branch and commit metadata. Inspect and establish the intended reference rather than bulk-accepting unexpected new results.

## Check still fails after acceptance
Inspect capture errors, missing baseline, accessibility findings, open change requests, and the selected PR policy. **Fail on differences** deliberately stays failed for a differing result even when accepted. Also check that you are looking at the same commit's check.

## Baseline did not update after merging
Confirm CI ran on the configured baseline branch and its run finished and was accepted. A pull-request approval alone does not advance it. If images or settings changed between the PR and merged build, carried approval may not apply.

## Live or Open Storybook fails
Open a fresh link from the run page. Links expire after an hour and builds after 30 days. Check whether that story supports Live. A screenshot can remain available after the interactive build expires.

## Native app never connects
Check capture mode, entry registration, story generation, and the bundled JavaScript. On Android, verify localhost cleartext access and x86_64. On iOS, use an arm64 simulator app, not a device build. See [Android](/android/) or [iOS](/ios/).

## Still stuck
Contact [support](https://framecheck.dev/help?topic=bug) with the run URL, commit, expected behaviour, actual error text, and relevant Storybook or uploader version. Redact secrets and customer data. Include the smallest reproducible story you are allowed to share.