Troubleshooting

Most issues come down to one of five things: no preview for screencli to open, a verdict it couldn't reach, a login it couldn't get past, the wrong URL, or an empty credit pool. Find your symptom below and jump to the fix.

screencli didn't run on my PR

The GitHub App triggers off your preview deployment, not the push itself. If nothing happened, work down this list.

• No preview deployment. This is the most common cause. screencli waits for a successful preview deploy to appear on the PR, then tests that URL. If your PR never produces a preview, there's nothing to open. Vercel, Netlify, and Cloudflare Pages post a GitHub Deployment that screencli picks up automatically. Cloudflare Workers Builds doesn't post a Deployment object — it posts a check plus a cloudflare-workers-and-pages[bot] comment instead, and screencli reads the Commit Preview URL out of that comment. Other CI that only posts a status check with no deployment and no recognized preview comment won't trigger a run.
• The deploy was production, not preview. screencli deliberately ignores deployments whose environment is production — it only ever tests previews. A PR that deploys straight to a production environment won't be tested.
• "Run on every PR" is off. Open the repo's settings (Settings → Integrations → Configure repos →, then pick the repo) and confirm the Run on every PR toggle is on. With it off, deployment events for that repo are skipped. See Configure a repo.
• The repo isn't connected — or the account isn't Pro. Connecting a repo for the first time is a Pro action; free accounts hit the paywall at the connect step. Check the repo appears as a watched repository on the Integrations page, and that your workspace is on Pro.
• The commit was already tested. Runs are idempotent per (repo, commit) — screencli tests each head SHA exactly once. Re-opening or re-syncing a PR on the same commit won't start a new run. Push a new commit to trigger a fresh one.

The verdict came back inconclusive

inconclusive means the run couldn't reach a pass/fail decision — it isn't a failing test. See Verdicts for the full model. Common causes:

• The preview timed out or was unreachable. If the preview deployment was slow, still building, or returned an error when screencli opened it, the run ends inconclusive. Re-run by pushing a new commit once the preview is reliably live.
• The preview is protected. A password-gated or access-controlled preview (Vercel Protection Bypass, Netlify password, etc.) blocks the browser before it reaches your app. Add a Preview deployment bypass token in the repo's settings — it's stored encrypted at rest. See Configure a repo.
• You ran out of credits mid-run. When the shared credit pool is empty, the run is finalized as inconclusive with an explicit credit reason (the PR comment says so too). See I'm out of credits below.

The test couldn't get past the login screen

If verifying the change requires a signed-in session and the agent got stuck at your sign-in page, it never had credentials to use.

• Give it a test account. In the repo's settings, fill in the Authentication section: an Email and Password for a dedicated throwaway account, plus plain-language Auth instructions the agent follows before the main task. Use {{email}} and {{password}} placeholders — they're substituted server-side just before the run, so the raw values never sit in the agent's context. Full walkthrough: Authentication.
• "Invalid origin" (or a similar rejection) from your own auth backend. This is a setting on your side, not a screencli bug: your auth framework only trusts a fixed list of origins, and the preview URL isn't on it. Add the preview URL — or a wildcard pattern that covers your preview domains — to your framework's trusted-origins allowlist (trustedOrigins in Better Auth, the equivalent in Auth.js / NextAuth, and so on). Tests that don't actually need a logged-in session will skip the login step on their own.

screencli tested the wrong URL

By default screencli tests the deployment URL GitHub reports on the PR. If that's not the address you want checked, override it.

• Set a Preview URL pattern. In the repo's settings, set Preview URL pattern using {{branch}}, {{sha}}, or {{short_sha}} as placeholders — for example https://{{branch}}.myapp.dev. Leave it blank to fall back to the deployment URL from GitHub. See Configure a repo.

Cloud recording from the dashboard won't start

Pressing Start Recording on the dashboard composer and getting an upgrade dialog instead of a run is expected on a free account.

• Cloud recording is Pro-only. Free accounts can sign in and view existing recordings, but starting a cloud run opens the upgrade paywall. Upgrade from Settings → Plan & Billing. To record for free without a plan, use the CLI locally instead.
• Both fields are required. The composer won't start until you've entered a URL and a prompt.

I'm out of credits

Runs are metered in credits — 1 credit = 1 agent step (one browser action). When the pool is empty, GitHub-App runs finalize as inconclusive with a credit reason and dashboard runs stop.

• Wait for the monthly refill. A Pro workspace refills to 500 credits on your monthly billing date. Credits are a shared pool across your workspace, so a teammate's runs draw from the same balance — check who's been running what. Your remaining balance is shown in Settings → Plan & Billing.
• Bring your own Anthropic key to run unmetered. Add your own key under Settings → Anthropic API key and the per-run credit meter is skipped — your credits display shows ∞ and token usage bills to your Anthropic account. Sandbox compute and storage still need a Pro plan for the cloud and GitHub-App flows. See Bring your own Anthropic key.

Still stuck?

• Check the recording itself. Open the run from your dashboard — the video shows exactly what the agent saw, and the verdict reason spells out which check didn't pass. That usually points straight at whether the problem is your app, your preview, or your test setup.
• Confirm you're testing a preview, never production. screencli only ever drives the preview deployment from your GitHub deployments; if a change only shows up in production, there's no preview for it to check.