Skip to main content

​
Overview

Most problems on Stardeck surface in one of three places:
  • In the chat with the agent — while you’re building.
  • In your sandbox preview — when testing changes before publishing.
  • On a deployment card — when publishing or deploying fails.
The fastest first move is almost always the same: tell the agent what you saw, or click Fix with Agent on a failed deployment. The agent can read errors, logs, and your app’s setup and fix most issues for you — you rarely need to interpret them yourself.
When something looks wrong, describe what you expected versus what happened. “The checkout button does nothing when clicked” is enough for the agent to start investigating.

​
While you’re building

Your sandbox preview shows your work-in-progress app. If a change isn’t showing up, give it a moment to rebuild, then refresh the preview. If it still looks stale, ask the agent to re-run or restart the preview.
Many features need an environment variable (an API key or secret) to work. If the app complains that something is missing or undefined, check that the required variable is set for the environment you’re testing. Secrets set for production aren’t automatically present in the sandbox, and vice versa — see Environments.
Your app reads and writes through a data store. While building, you’re working against sandbox data — a private copy. If a table or column seems missing, confirm the change was actually made, and remember that sandbox and production data are separate (this matters a lot at publish time — see below).
You don’t have to accept a bad direction. You can ask it to undo or try a different approach, or use conversation forking to branch off from an earlier, good point in the conversation.

​
When publishing or deploying fails

When a publish or deployment fails, the deployment card shows:
  • A plain-language summary of what went wrong.
  • A Show logs toggle for the full, verbatim deployment logs.
  • One of two actions:
    • Fix with Agent — hands the distilled error (and the deployment context) to the agent to diagnose and fix.
    • Redeploy — shown when the failure looks temporary; just runs it again.
Some failures have nothing to do with your app — a network blip, a package download timing out, a brief service hiccup. These are transient, and the card offers a Redeploy button. Click it to try again. If it keeps failing, treat it as one of the cases below and use Fix with Agent.
Before going live, your app is compiled and type-checked. If the code references something that doesn’t exist or has the wrong shape, the build stops and the deployment fails. Click Fix with Agent — it receives the exact error lines and fixes the code. These are the most common failures.
This is the trickiest one, and worth understanding.While you build, your app runs against your sandbox data — a copy you can change freely. When you publish, the app runs against your live (production) data instead. If you changed your data structure (added a table or column) in the sandbox but it was never applied to production, the live deployment can fail even though everything worked while you were building. The same applies to preview deployments of a branch, which use that branch’s own data.
A deployment can fail this way even when everything looked fine in the sandbox — the sandbox never sees your production data structure, so a passing preview is not a guarantee that publishing will succeed.
What to do: click Fix with Agent. We automatically tell the agent which data environment this deployment ran against versus the one your sandbox uses, so it checks whether a schema change simply hasn’t been applied to production yet — rather than blindly rewriting your code.
For engineers: apps develop against a per-project sandbox data-store branch. At deploy time, sandbox-authored schema operations are replayed onto the target branch — the production-mapped branch for a production deploy, or the per-branch preview branch for a branch preview. The deploy fails here when the target’s schema diverges from the sandbox’s (a table/column never promoted, or generated data-store types built against the sandbox schema). The standalone build check never touches the data store, so it can’t surface this — only the deploy-time replay can.
If publishing would make a destructive change to your production data (for example, dropping a table or column), we pause and ask you to confirm before continuing, so you don’t lose data by accident. Review the change and confirm only if you’re sure. Preview deployments don’t ask, because preview data is disposable.

​
Reading the full logs

If you want the raw detail, expand Show logs on the failed deployment card. The plain-language summary is generated from those same logs, so you usually don’t need to read them — but they’re there when you (or the agent) want the complete picture.

​
Still stuck?

If the agent can’t resolve it and the logs don’t make it obvious, reach out through support with a description of what you were doing and what failed.