# Troubleshooting URL: https://docs.xodia.ai/troubleshooting Last updated: 2026-10-22 Fixes for the problems people meet most often. When Xodia shows an error, its message says what went wrong, there's often a button for the fix, and a Reference you can send us if you're still stuck. ## The preview won't start ### Preview hours are used up **Why:** the workspace used this month's preview hours, or the trial's hours, which are one total for the whole trial. **Fix:** upgrade in Billing & usage, or wait until the hours reset on the 1st of next month. Meanwhile you can edit a folder on your computer with local folder mode, which uses no preview hours. On Pro and Agency, previews on your own Cloudflare account don't use them either. **Error:** `plan_limit` with the action `upgrade_plan`. ### Too many previews are running **Why:** each plan runs a number of previews at the same time, and they're all in use. **Fix:** Xodia names the previews that are running; stop one of them, or upgrade. A preview also stops by itself after 20 minutes without use. ### The site's own build or dev server fails **Why:** something in the code, its packages or a missing environment variable stops the dev server. **Fix:** ask your AI with the Fix kind; it reads the preview's logs and fixes the cause. If the site needs a variable your host sets, copy it into the preview: see [Copy variables into your preview](https://docs.xodia.ai/integrations/hosts#variables). If Xodia says it was updated, restart the preview to get the latest fixes. ## A project says it's locked **Why:** the workspace has more projects than its plan includes, often after moving to a smaller plan. Its most recently opened projects stay open and the rest are locked. Nothing is deleted. **Fix:** upgrade, or delete another project, and the locked one opens again at once. Only owners and admins can change the plan. **Error:** `project_locked` with the action `upgrade_plan`. ## Xodia asks for a card **Why:** every workspace needs a card on file before anyone can open it. Nothing is charged; the first card starts the free trial. **Fix:** an owner or admin adds the card on that step. Other members see Waiting for a card and choose Check again once it's added. See [Add a card and start the trial](https://docs.xodia.ai/get-started/account#trial). **Error:** `card_required` with the action `add_card`. ### You can't add a card yet The workspace owner's email address has to be verified first. Open the link in the email from Xodia, or choose Resend email, then choose I've verified it. The error is `email_unverified` with the action `verify_email`. ## You can't edit a branch **Why:** on Free, only the project's default branch can be edited. Other branches are view only. **Fix:** switch to the default branch, or upgrade to work on branches. ### Your access is read only After the workspace moved to a plan with fewer seats, the members past the seats can look but not change anything. Ask an owner to upgrade or free a seat. The error is `seat_read_only`. ## Your AI can't connect - Use the address exactly as Xodia shows it, with Streamable HTTP (sometimes called HTTP) as the transport. - Choose OAuth, and leave any key or token field empty. The app asks you to sign in to Xodia in your browser. - Sign in with the account your projects are in. - After sign-in, name xodia in your message: Use xodia to work on my Xodia requests. Each app's own steps and fixes: [Claude Code](https://docs.xodia.ai/ai/claude-code#troubleshooting), [Claude app](https://docs.xodia.ai/ai/claude-app#troubleshooting), [Cursor, Codex, VS Code and others](https://docs.xodia.ai/ai/other-apps#troubleshooting). ### The ask box says to start the helper Your AI runs from the ask box through the Xodia helper on your computer, and it isn't running. Start it with your command from Xodia and leave the terminal open: see [The Xodia helper](https://docs.xodia.ai/ai#helper). The error's action is `start_helper`. ### Your AI says a skill isn't on your plan Framework and styling packs come with every plan. CMS and host packs come with Starter, Pro and Agency; on Free your AI works without them. ## A CMS token is refused **Why:** the token was revoked, expired or lost access in the CMS. **Fix:** open the project's Content tab, choose Reconnect, and paste a new token. The error's action is `reconnect_cms`. ## A deploy failed In the project's Settings, Publishing, open the failed build and choose Fix with your agent: the error goes to your AI as a fix request. Before you publish next time, choose Check the build in the Publish dialog to run a production build first. ## Xodia says it's being updated Xodia is deploying a new version, which takes a few minutes. The message says when to try again. ## Still stuck Write to us from the [support page](https://xodia.ai/support). Include the Reference shown under the error message, and your Workspace ID from Organization settings, General, so we find the problem at once. We aim to reply within 2 business days. > **Tip:** Errors also come back to your AI in the same shape, with a hint written for it. Ask your AI what an error means and it can often fix it itself.