Troubleshooting
Common issues and solutions related to sandcastles.
The preview shows a blank page or an error
The latest version has a code issue. Open the sandcastle's detail page and check the version history. If the most recent edit introduced the problem, roll back to the previous version and try a different approach to the edit. If every version is broken, open the editor and look at the code — common causes are a missing Component export or an unmatched JSX tag.
The AI built something different from what I described
The plan was too vague. The AI interprets general requests broadly. Re-run the conversation and be more specific: name the fields, describe the layout, reference a concrete example ("like a Trello board, but grouped by approval status"). Reviewing and refining the plan before scaffolding saves significant rework.
A collection shows zero documents after scaffolding
Seed data may have failed silently. Open the sandcastle's Data page and check whether the collection exists. If the collection exists but is empty, the scaffold step may have skipped seeding. Ask the AI in chat: "Seed the [collection name] collection with five example documents."
If the collection does not exist at all, ask the AI to create it: "Add a collection called [name] to the [sandcastle name] sandcastle."
The app loads but shows stale data
The query cache may be out of date. Sandcastle queries cache results briefly (30 seconds). If you edited data directly on the Data page or through the subagent, the app may not reflect the change immediately. Refresh the preview page. If stale data persists, the app's query filters may be excluding the updated records — check the filter logic.
I can't edit the sandcastle
You don't have edit access. Check your permission level. Only users with edit or admin access (or workspace admins) can modify the code, rebuild the preview, or reset data. Ask the sandcastle's owner or a workspace admin to grant you edit access through Workspace > Permissions > Resources.
I can't delete the sandcastle
You need admin access. Only the owner, users with admin permission, and workspace admins can delete a sandcastle. If you have admin access but deletion still fails, check whether the linked subagent has active scheduled triggers — disable them first, then delete.
The linked subagent can't read or write to a collection
The subagent may have been unlinked or the collection name is wrong. The linked subagent's state tools are scoped to this sandcastle's collections. If the subagent was manually unlinked or replaced, the state tools lose their scope. Check that the subagent is still linked on the sandcastle's detail page. If the collection name in the tool call doesn't match an existing collection, the call will fail — collection names are case-sensitive.
The preview won't rebuild
A build may already be in progress. The build system queues one build at a time. Wait a moment and try again. If repeated rebuilds fail, check whether the code has a syntax error — open the editor and look for red underlines or parse errors. A code change that doesn't parse will fail the build silently.
Data browser shows "No collections"
The sandcastle was created without state. Not every sandcastle uses collections — simple display-only apps may have been scaffolded without them. If you need collections now, ask the AI: "Add a collection called [name] to [sandcastle name] with fields [list]."
I rolled back to a previous version but the data didn't roll back
Versions are code-only. Rolling back restores the app's code to a previous state, but data in collections is not versioned. Documents that were created, modified, or deleted between the current version and the rollback version remain as-is. If you need to reset the data, use the Reset action on the Data page — but be aware this deletes all documents in the collection.
Still need help?
Contact your workspace administrator or open a support ticket. When reporting an issue, include the sandcastle name, the version you're on, and the collection name if the problem involves data.