Troubleshooting
Most issues in Castaly are recoverable from the workspace. Start with the state label, the message in Chat, or the action shown in the Preview tab, then follow the matching path below.
For the full state map, see Project States. For recovery actions by blocker type, see Resolve Blockers.
Start with the state
Section titled “Start with the state”Read the label on the Project card, workspace header, Graph, or Preview tab. Most states point to one clear next step.
| What you see | What it usually means | What to do |
|---|---|---|
| Building, Testing, or Publishing | Castaly is still working. | Wait for the current run to finish. |
| Needs your input | Castaly needs a decision or clarification. | Reply in Chat. |
| Build blocked | The Spec has a conflict that must be resolved first. | Resolve the conflict in Chat, then continue. |
| Configuration required | A required Runtime Secret is missing. | Add the secret before publishing. |
| Build failed, Preview failed, or Publish failed | A run failed after it started. | Use the recovery action shown in the workspace. |
| Preview expired | The running preview link timed out. | Use Resume to restore the same build’s Preview. |
You can’t type in Chat
Section titled “You can’t type in Chat”The Chat composer is disabled while the Project is busy. This can happen during setup, an active Chat run, or a running Build.
This is expected. Castaly locks new input and Spec edits so they do not collide with work already in progress.
Wait for the current run to finish. The composer re-enables automatically; you do not need to reload the page.
A file won’t attach
Section titled “A file won’t attach”Castaly rejects a file before attaching it when the file type, format, or size is not supported. The upload message should tell you what to change.
Check the accepted inputs in Supported Inputs. Archives and code repositories are not supported; add the individual files or references instead.
You’re out of credits
Section titled “You’re out of credits”When your credits run out, paid AI work, new Builds, and over-quota usage pause. Your Projects, Specs, and published work remain available.
To continue, add a credit pack, upgrade your plan, or wait for monthly credits to renew. See Plans & Credits for the live balance and Plans & Usage for how credits work.
Preview won’t open
Section titled “Preview won’t open”The Preview tab shows the current preview condition and the available action.
| Symptom | What it means | What to do |
|---|---|---|
| No preview yet | No build has created a Preview. | Run Build. |
| Preview is being prepared | Castaly is deploying or restoring the Preview. | Wait for the status to finish. |
| Preview expired | The Preview link timed out. | Use Resume to restore it. |
| Preview failed | Castaly could not prepare the Preview. | Retry the Preview action shown in the workspace. |
| Runtime configuration required | A required Runtime Secret is missing. | Add the secret before publishing. |
| Build needs your input | A blocker must be resolved before a Preview can be created. | Resolve the issue in Chat, then run Build again. |
See Preview Your Project and Runtime Secrets.
Build won’t start
Section titled “Build won’t start”Build only starts when the Spec is ready and the required approval step is complete.
If you see Plan ready, review the Build Plan and accept it. If you see Build blocked, Castaly found a Spec conflict that needs clarification before it can safely build. See Start a Build and Resolve Spec Conflicts.
Publish won’t start
Section titled “Publish won’t start”Publishing is blocked only by issues that already exist. Publish usually waits on one of two things:
- Configuration required: add the required Runtime Secret from Project Workspace → gear icon → Runtime Secrets.
- Build blocked: resolve the Spec conflict in Chat before building again.
Clear the blocker, then publish again. See Publish Your Project.
You can’t sign in
Section titled “You can’t sign in”Use Forgot password on the login screen to reset your password.
If you can sign in but need to update account details, open Account Settings. See Account Settings.
Billing or credit history looks wrong
Section titled “Billing or credit history looks wrong”Use Plans & Credits for your current balance, plan, and credit packs. Use Credit Activity for the ledger of grants, purchases, usage, refunds, and adjustments.
If the number still looks wrong after checking both views, contact support and include your account email and a screenshot of the row or balance you are asking about.
Still stuck
Section titled “Still stuck”If a setup, Build, Preview, or Publish failure is not a Spec conflict, missing Runtime Secret, or credit issue, it may be platform-side.
- For Project work, describe the issue in Chat so Castaly can recover with the right context.
- For account, billing, or platform issues, open Account Settings → Contact Us and email support@castaly.ai.
For definitions, see Glossary. For support scope, see Support Policy.