Troubleshooting
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.
On this page
- The preview won't start
- Preview hours are used up
- Too many previews are running
- The site's own build or dev server fails
- A project says it's locked
- Xodia asks for a card
- You can't add a card yet
- You can't edit a branch
- Your access is read only
- Your AI can't connect
- The ask box says to start the helper
- Your AI says a skill isn't on your plan
- A CMS token is refused
- A deploy failed
- Xodia says it's being updated
- Still stuck
The preview won't startLink to this section
Preview hours are used upLink to this section
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 runningLink to this section
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 failsLink to this section
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. If Xodia says it was updated, restart the preview to get the latest fixes.
A project says it's lockedLink to this section
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 cardLink to this section
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.
Error: card_required with the action add_card.
You can't add a card yetLink to this section
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 branchLink to this section
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 onlyLink to this section
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 connectLink to this section
- 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, Claude app, Cursor, Codex, VS Code and others.
The ask box says to start the helperLink to this section
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. The error's action is start_helper.
Your AI says a skill isn't on your planLink to this section
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 refusedLink to this section
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 failedLink to this section
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 updatedLink to this section
Xodia is deploying a new version, which takes a few minutes. The message says when to try again.
Still stuckLink to this section
Write to us from the support page. 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.