> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common things that go wrong when building on Stardeck, and how to get unstuck

## 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.

<Tip>
  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.
</Tip>

<Note>
  Troubleshooting a physical Edge machine, printer, cash drawer, or display? See [Troubleshoot
  Stardeck Edge](/stardeck-edge/troubleshooting).
</Note>

## While you're building

<AccordionGroup>
  <Accordion title="The preview doesn't reflect my latest change">
    Your [sandbox preview](/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.
  </Accordion>

  <Accordion title="The app errors about a missing key, token, or setting">
    Many features need an [environment variable](/environment-variables) (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](/environments).
  </Accordion>

  <Accordion title="Data looks wrong, empty, or out of date">
    Your app reads and writes through a [data store](/data-stores/overview). 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).
  </Accordion>

  <Accordion title="The agent seems stuck or went down the wrong path">
    You don't have to accept a bad direction. You can ask it to undo or try a different approach, or
    use [conversation forking](/conversation-forking) to branch off from an earlier, good point in the
    conversation.
  </Accordion>

  <Accordion title="Feature branch merge or deploy surprises">
    [Feature branches](/branching) isolate code, chat, and sandbox runtime — not the project's
    shared sandbox data. If merge says the main agent is busy, wait for that run to finish and
    retry (merges are not queued). Feature branches can create shareable preview deployments, but
    production publishing stays on the default branch. Merge and verify there before publishing.
  </Accordion>
</AccordionGroup>

## When publishing or deploying fails

When a publish or [deployment](/publishing-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.

<AccordionGroup>
  <Accordion title="Temporary glitches (network, timeouts)">
    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**.
  </Accordion>

  <Accordion title="Code or type errors found at build time">
    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.
  </Accordion>

  <Accordion title="Data store differences between your sandbox and your live app">
    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.

    <Warning>
      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.
    </Warning>

    **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.

    <Note>
      **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.
    </Note>
  </Accordion>

  <Accordion title="Schema changes that need confirmation">
    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.
  </Accordion>
</AccordionGroup>

## 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.

## Surfaces and Modules

<AccordionGroup>
  <Accordion title="A Surface is missing or not live">
    Open the app's Surfaces card in Settings. **Not deployed yet** means the Surface is declared but
    needs a production publish. **Removed at tip** means it is no longer on the current branch.
    Use **Sync** after committing, then publish so ready Surfaces go live. Dedicated non-root Surface
    URLs are production-only. Full details: [Surfaces](/app-structure/surfaces).
  </Accordion>

  <Accordion title="A Module is missing or setup failed (Alpha)">
    Modules are Alpha and available only to selected organizations. If setup failed while starting
    from Modules, use **Retry setup** on the project — progress is retained, and you may need to
    reconfirm if a Module source changed. If a Module doesn't appear in the catalog after you expected
    it to, open **Settings → Modules** and Sync, or ask the agent. Installation brings the capability;
    the agent still does app-specific connection work. See [Modules](/app-structure/modules).
  </Accordion>
</AccordionGroup>

## Still stuck?

If the agent can't resolve it and the logs don't make it obvious, reach out through
[support](/support-sla) with a description of what you were doing and what failed.