Troubleshooting & edge cases

Most problems fall into a handful of buckets: something didn’t load, a gate is guarding you, you ran out of allowance, an invite went to the wrong place, or the CLI can’t see your project. This page walks through them in detail, symptom first, then why it happens, then the fix.

Projects & the home screen

“We couldn’t load your projects”

You open the home screen and see a red banner: We couldn’t load your projects. This is usually temporary. Try again in a moment., with a Try again button.

Why it happens. The home screen fetches your project list on load. If that one request fails, the banner appears and stays until a successful reload, it doesn’t retry on its own. The common causes:

A brief network blip, or the server was cold-starting (the first request to a freshly-woken instance can miss its auth token by a fraction of a second).
Your sign-in session expired between opening the tab and the request going out.
On a local dev server (for example localhost:3001): the app can’t reach the projects API at all, usually because apps/web/.env.local is missing or has stale Firebase Admin credentials, so the API returns a 500.

Fix. Click Try again, it re-runs the fetch, and a transient blip clears immediately. If it persists across a full page reload:

Confirm you’re still signed in (reload; if you’re bounced to the login screen, sign in again).
On a local dev server, check that apps/web/.env.local has valid FIREBASE_ADMIN_* values, then restart the dev server.

A project is missing from the list

You know you created a project but it isn’t on the home screen.

Why. The list is scoped to your active organization. A project created under a different org won’t show while another org is active.

Fix. Switch organizations from the rail’s org switcher. If it’s still missing, you may have been removed from the org that owns it, ask an owner or admin.

A project card opens the “How do you want to start?” screen instead of the workspace

Why. A freshly created project stays “pending” until you pick an option on the start chooser. Until then, opening its card returns you to that chooser rather than the workspace.

Fix. Choose Start from scratch (or import) once, and from then on the card opens the workspace normally.

Gates & the workspace

A gate is locked and won’t open

Why. Gates are linear. A gate stays locked until the previous required gate is committed. This is deliberate, you can’t sensibly decide a data model before the features exist.

Fix. Go back and commit the earlier gate. The next one unlocks immediately. See commit gates.

A gate is marked “stale”

Why. Something the gate read from an upstream gate changed after this one was committed, so its inputs no longer match. Staleness is a flag, not an error, it’s the system telling you a decision may need revisiting.

Fix. Open the stale gate, review what shifted upstream, and re-commit. If several gates went stale at once (common after editing the brief or the feature list), let the Downstream Review reconcile them in one pass.

A gate won’t let me commit

Why. You can’t commit an artifact that’s still incomplete, the gate checks for its required fields first.

Fix. The workspace shows what’s missing. Fill those in, then commit. If you’re not sure what’s incomplete, ask the gate’s agent in the chat, “what’s still missing here?”

The workspace looks frozen while the AI is working

Why. During generation a sticky warning appears (Do not leave this page during AI generation) and controls quiet down. That’s expected, generation is a foreground operation.

Fix. Wait for it to finish. Don’t navigate away or close the tab mid-generation, it can interrupt the write.

Gate 08 has a number badge on it

Why. That badge counts screens the Downstream Review added or changed on its last run that you haven’t reviewed yet.

Fix. Open Gate 08 and review the flagged items. The badge clears as you go.

A panel is read-only or the drag handles don’t respond

Why. You may be viewing a project you can see but can’t edit (for example a locked project, or one where your role is view-only). Read-only panels still expand so you can read them; they just can’t be edited.

Fix. If you should have edit rights, check the project isn’t locked and that your org role allows editing.

Generation & running out

Generation stops partway through

Why. You’ve hit your allowance. On Free, that’s the monthly token limit. On Pro, it’s your pooled tokens and your prepaid credits both being exhausted. When that happens, a paywall appears instead of the next response.

Fix.

Free: wait for the monthly reset, or upgrade to Pro.
Pro: top up prepaid credits from Settings → Usage & billing. Turn on auto-reload so you get a one-click top-up before you hit zero next time.

See the billing FAQ for the full picture.

“AI unavailable for this database type”

Why. The composer disables AI for a manual database path where automated generation doesn’t apply.

Fix. Fill in that step manually; the rest of the workspace is unaffected.

An upload didn’t process, or “no content could be extracted”

Why. The file couldn’t be read, common with scanned PDFs (images of text, not text) and unsupported formats.

Fix. Re-export as a text-based PDF, or paste the content directly into the chat using the recovery card that appears. Plain formats (Markdown, .txt, .docx, real PDFs) extract most reliably.

Billing

Payment failed / the org is “past due”

Why. Stripe couldn’t charge your card on the last attempt. Your org is marked past_due and you get an email. Access continues while Stripe retries.

Fix. Update your card in the billing portal: Settings → Usage & billing → Manage.

Billed seats and member count disagree

Why. Seats reconcile to the accepted member count, but a brief mismatch can appear right after someone joins or leaves, before reconciliation runs.

Fix. Use Sync seats on the billing panel (owners/admins), or wait, it reconciles on its own.

A discount code didn’t apply

Why. Codes apply at checkout, not retroactively. Also check the code hasn’t expired, hasn’t hit its redemption cap, and meets any minimum-spend or first-time-only restriction.

Fix. Enter the code in the promotion-code field at checkout. If it’s rejected there, the restriction it violates is usually named in the error.

A refund didn’t restore my credits

Why. This is expected for a subscription refund, the subscription grants tokens, not credits, so refunding it doesn’t touch your credit balance. Only a credit-pack refund reverses credits.

Teams & invites

I can’t invite anyone, “requires Pro”

Why. Seats cost money, so adding one needs the org on a paid footing: a live Pro subscription, an admin-set plan, or a comp.

Fix. Subscribe the org to Pro (owner/admin), or ask a CubeDot admin to comp it.

The invite recipient can’t accept

Why. An invite must be accepted with the account that uses the exact invited email address, and the link expires after 7 days. Signing in with a different account, or after expiry, both fail.

Fix. Have them sign in with the invited address. If it’s expired, an admin can extend it (the Extend action) or send a fresh one. If email delivery isn’t configured, use Copy link to share the invite directly.

The invite email never arrived

Why. Transactional email is best-effort and can be dormant if the mail domain isn’t verified yet. Nothing about the invite itself is broken, only the delivery.

Fix. Use Copy link on the pending invite (both the web People panel and the admin org page have it) and send the link yourself.

I removed the wrong person / I can’t remove the owner

Why. The owner can’t be removed while they’re the owner, that would leave the org without one.

Fix. To replace an owner, transfer ownership first (the old owner becomes an admin), then adjust roles. Re-inviting a removed member is just a normal invite.

The CLI & MCP

Stuck on “Connecting…”

Fix. Quit your AI coding agent fully and reopen it to clear the stale connection state. (A reload inside the agent is often not enough.)

“cubedot: command not found” / “not recognized”

Why. The global install isn’t on your PATH in the current shell.

Fix. Open a new terminal window and run the command again. If it still fails, confirm the global install succeeded (npm ls -g @cubedot/cli).

An “Authenticate” / “Needs Auth” button in my agent

Why. That’s your agent’s generic MCP auth prompt.

Fix. Don’t click it, CubeDot signs in automatically with the project key written by cubedot init. Clicking it can send the agent down the wrong auth path.

`cubedot work` lists nothing

Why. work is dependency-aware: it only lists functionalities whose prerequisites are already done. An empty list means either everything reachable is in progress or done, or nothing is unblocked yet.

Fix. Run cubedot progress to see the overall state. If early functionalities aren’t done, finish those to unblock the rest. If your spec has no committed dependency graph yet, work has nothing to order.

`cubedot sync` reports drift

Why. The local projection differs from the spec on the server, usually because the blueprint changed after you last synced, or local files were edited by hand.

Fix. sync refreshes the projection; review what it flags. If your code has diverged intentionally, record it as a deviation or devchange rather than forcing the spec to match.

A `devchange` was refused

Why. The CLI pre-checks capabilities and refuses a devchange on a project where devchange is disabled, rather than half-applying it. Importantly, it refuses only that operation, your other transitions, reports, notes, and deviations keep flushing.

Fix. Nothing is stuck. If you need devchange on that project, it has to be enabled server-side; everything else continues normally.

I got signed out unexpectedly

Why. Sessions expire. After expiry, the next protected request fails and you’re returned to sign-in.

Fix. Sign in again. If it recurs quickly, clear the site’s cookies/storage and sign in fresh.

The wrong organization is active

Why. Actions (creating projects, viewing lists, billing) apply to your active org, which persists across sessions.

Fix. Switch orgs from the rail’s switcher before creating or looking for a project.

Still stuck?

If none of the above fits, reach us at cubedot.ai with what you did, what you expected, and what happened.