Troubleshooting

Can’t find your problem here, or need us directly? See Getting Help.

Signing in

“Invalid or expired verification code.” — Email codes expire quickly. Request a new one and check your spam folder if it doesn’t arrive within a minute or two; each code is single-use.

Touch ID doesn’t show up on the sign-in screen. — Native passkeys need macOS 15 or later. On macOS 13–14 the app runs fine, but sign-in falls back to the email code every time. You can still add a passkey once you upgrade macOS.

“No passkey on this Mac yet.” — Passkeys are tied to the specific Mac they were created on; they don’t sync between machines. Sign in with your email code on this Mac, then add a passkey from Account → Passkeys.

Passkey setup isn’t available right now. — A couple of app windows (like the pop-out Chat or Code windows) can’t run the Touch ID setup ceremony. Open Account from the main editor window and add the passkey there.

Git-powered features (checkpoints, Sync, GitHub, cloud runs)

A macOS dialog says “git” requires the command line developer tools. — Plyed uses Apple’s built-in git tool for AI undo checkpoints, Sync to Plyed, GitHub backup, and cloud agent runs. Click Install in that dialog and wait for the one-time download; those features then work normally on this Mac from then on. Choosing Not Now leaves them unavailable — everything else (canvas editing, AI edits, publishing) keeps working — until you install the tools; reopen the feature you were using to see the dialog again. See Install & Sign In.

A project won’t open or the preview won’t start

Plyed shows a status message in the top bar while it works, and a matching line in the Logs tab (open a project’s Code view) if something fails.

“Dependency install failed — switch tabs or reopen to retry.” — Plyed couldn’t install the project’s packages. This is almost always a network problem or a full disk. Check your connection and free disk space, then switch away from the project tab and back (or close and reopen the project) to retry. The Logs tab shows the underlying install output if you want the detail.

“Dev server failed — switch tabs or reopen to retry.” — The local preview server couldn’t start. Reopening the project retries it. If it keeps happening, check the Logs tab — a broken astro.config.mjs or a bad environment variable can prevent the site from building; see Environment Variables.

Trying to open several projects at once and one won’t start its preview. — Plyed can only run a limited number of live previews at the same time. Close another open project tab, then reopen this one.

“Editing bridge not responding — reloading preview…” — Plyed reloads the preview automatically when this happens; you don’t need to do anything. If editing still doesn’t work afterwards, check the Logs tab for a script error in the page, or reload the project.

“Trust this project?” — Plyed runs a project’s own code (its dev server, config and any install scripts) only after you trust it. Projects you create from a starter are trusted automatically; a project someone shared with you, or one cloned from a repository, asks first. If the project defines install scripts, the prompt names them. Choose Trust and open if you trust where it came from; otherwise Cancel — the preview won’t start and Plyed won’t run anything from the project until you decide.

“This project isn’t trusted yet, so Plyed won’t run its code.” — You cancelled the trust prompt, and then tried to publish or start the preview. Reopen the project and choose Trust and open.

Editing on the canvas

“Add to every page using PageLayout?” — You’re adding straight into <body>, which belongs to the layout, so the element would show on every page that uses it. Click Add to every page if that’s what you want, or Cancel and select something inside the page’s main content to add to this page only. See One page, or every page?

“… is this page’s layout — deleting it would remove the whole page.” — The element you tried to delete is the layout that wraps the page. Select the thing you want to remove inside it instead.

“… holds the <slot /> of … — deleting it would hide the content of everything that uses …” — Use Unwrap to remove the wrapper but keep the slot, or edit that component in Source. See Layouts & Slots.

“Slots go in components and layouts …” — A slot can’t be added to a page. Add it while editing the component itself.

Publishing problems

“Build failed — check the logs.” — Your site didn’t compile. Open the project’s Logs tab for the specific error — this is usually a code issue introduced by a recent edit; undo it from History or fix it and republish.

“Deploy is too large for your plan.” — Your published site’s files went over Plyed’s publish size limit — usually large, unoptimized images or video. Compress or remove large assets from Assets (the panel can convert large photos to AVIF) and republish.

A raw too_many_files message instead of a friendly one. — Your project has more files than a single publish can include, typically from a very large asset folder. Remove unused files and republish.

“Free plan includes 1 site — upgrade to publish more.” — You’ve reached your plan’s published-site limit. (You’ll see this exact wording even on a paid plan that’s reached its own, larger limit — check Plans & Credits for your actual number.) Unpublish a site you no longer need, or upgrade in Account.

The name you want is already taken. — Site names on plyed.cloud are first-come, first-served across all Plyed users. Try a different name.

“Preview branches need a paid plan — upgrade to publish previews.” or “Your plan allows N previews per site — delete one or upgrade.” — See Publishing Your Site for how preview branches work, and delete an old preview from the same panel to free up a slot.

AI Chat

“Out of AI credits — upgrade in Account.” — You’ve used your plan’s included credits (and any purchased credits) for this period. See Plans & Credits to check your usage or buy more.

“This model needs a paid plan — the free plan uses the default model. Pick auto or upgrade in Account.” — The Free plan always uses the default model. Switch the model picker back to the default (or auto), or upgrade for the full model picker.

“The model stopped responding — try again.” or “AI is temporarily unavailable — try again in a moment.” — A momentary hiccup on the AI provider’s side. Resend your message after a few seconds.

GitHub backup

“Sign in to sync this project.” — Backing up to GitHub needs your Plyed account signed in, separately from your GitHub connection. Sign in, then push again.

“Session invalid. Sign out and back in.” — Your Plyed session expired. Sign out and back in from Account, then retry the push.

If pushing to GitHub fails after that, your personal access token may have expired or lost its repo scope — disconnect and reconnect it from the Git popover; see Back Up to GitHub.

Sanity CMS

“Sanity packages did not land in node_modules. Check the console, then press Connect again.” — The Sanity install didn’t finish, usually a network hiccup. Press Connect again in the CMS panel.

“You’re not signed in to Sanity — sign-in is running in the Code window terminal.” — Sanity’s own login runs in a terminal in the Code window. Switch to that window, finish signing in with your Sanity account in the browser tab it opens, then press Deploy schema or Save again in Plyed.

Invalid Project ID or Dataset. — Project IDs are lowercase letters, digits, and dashes (you can paste the full sanity.io/manage URL and Plyed will extract the ID). Dataset names allow lowercase letters, digits, dashes, and underscores — production is the default.

Environment variables

“Keys must look like PUBLIC_API_URL (letters, digits, underscores).” — Environment variable names can only contain uppercase/lowercase letters, digits, and underscores. Rename the key and save again.

After saving a variable, remember to Stop dev / Start dev in the top bar — the preview only picks up new values on the next start.