Troubleshooting

"I pushed but my sandbox didn't update"

Roughly fifteen seconds after a successful push you should see your change. If thirty seconds in nothing's changed, work through these:

1. Check you actually pushed

Run git log origin/main -1 and confirm the latest commit is the one you expect. If it shows an older commit, your push didn't go through. Push again.

2. Check GitHub received the webhook

In your repo on GitHub: Settings → Webhooks. Click the Hatchik webhook. Recent deliveries should show your last push with a green tick. A red cross means the webhook failed — click it for the response body, it usually says why.

3. Check the rate limit

If you've been pushing rapidly (more than six times in five minutes for the same sandbox), you've hit the redeploy rate limit. Wait a few minutes and try again.

4. Trigger a redeploy directly

Pull your deploy URL and token from AI_CONTEXT.md and POST to it manually:

curl -X POST https://hatchik.com/api/tenants/<your-slug>/redeploy \
  -H "X-Deploy-Token: <your-deploy-token>"

If this returns a 200, the issue was the GitHub webhook (not the deploy itself). If it returns 500, the deploy is failing — the response includes the last 50 lines of the redeploy log, paste it into your AI tool and let it debug.

5. Check status

If status.hatchik.com shows the sandbox host degraded, that's us — we'll be on it.

"My AI tool can't read AI_CONTEXT.md"

Symptom: your AI tool keeps editing the wrong files, or it doesn't know where your sandbox is, or it asks you for things that are in AI_CONTEXT.md.

Cursor, Windsurf, Cline, Antigravity

These auto-index the open folder. Make sure you've opened the cloned repo root (the folder with AI_CONTEXT.md at the top), not a parent or a child. Open the chat and ask "what's in AI_CONTEXT.md?" — if it answers correctly, you're set.

Claude Code or Codex

Drag AI_CONTEXT.md into the chat at the start of your conversation, or type @AI_CONTEXT.md to reference it. These terminal tools don't auto-read every file — they need an explicit pin.

ChatGPT, Gemini, Grok, or Comet (browser)

These need an explicit file upload. Use the attach button next to the prompt box, pick AI_CONTEXT.md from your repo folder, and ask "summarise what you see in this file" before doing anything else.

Universal fallback

Copy-paste the entire contents of AI_CONTEXT.md into your AI tool's chat as a single message, with the text "Read this carefully before answering anything else. Then say 'understood' and wait for my first prompt." That works in every AI tool that's ever existed.

See AI tool setup for the per-tool detail.

"I got the magic-link email but the link doesn't work"

Magic links are single-use and expire in 30 minutes. The most common reasons they "don't work":

• You clicked it once already (some email clients pre-fetch links to scan them — Outlook, Gmail's spam scanner — consuming the token before you click).
• You opened it more than 30 minutes after receiving it.
• You're on a different device or browser to where you requested it (rare, but some browsers strip the token).

Fix: go to hatchik.com/account and request a new sign-in link. They're free and unlimited. If three new links in a row all fail, email us — there's something else going on.

"I deleted my sandbox by accident"

Don't panic. We keep a 14-day grace period before fully purging a deleted sandbox.

1. Go to hatchik.com/restore-sandbox.
2. Sign in with the email on your account.
3. Click "Restore" on the sandbox you want back. The Docker stack is rebuilt and your data, code and customers come back to the same subdomain.

If 14 days have passed since deletion, the volumes are gone. Even then, email us — we keep encrypted backups for Launch-tier sandboxes for 14 days beyond the purge, so we may still be able to restore the last good snapshot.

"My sandbox feels slow"

There are a few common reasons:

You're on the free Sandbox tier

The free tier shares a Hetzner CAX21 host with other sandboxes. We cap concurrent provisions at three to keep things responsive but if a few hundred sandboxes are all under load you'll see queuing on writes. The fix is to upgrade to Launch — your sandbox moves to its own VPS in your chosen region. That's the right step once you've got real users.

Your AI tool added an unindexed query

Common pattern: your AI added a feature that runs a Postgres query with no index. Open Studio at yoursubdomain.hatchik.com/studio, run EXPLAIN ANALYZE on the slow query, and ask your AI tool to add the missing index migration.

Your app is making a lot of round-trips

If your front end is doing twenty separate Supabase queries on page load, that's twenty network round-trips. Ask your AI tool to batch into a single query or to use a database view.

If none of those, email us with the slug and a typical slow URL. We can pull the per-tenant caddy logs and the Docker stats from the host side.

"My AI tool edited a substrate file and now nothing works"

Most common one we see in week one. Symptoms: deploys 500, the sandbox doesn't come back up, Supabase Studio is unreachable. Almost always caused by an AI edit to docker-compose.yml, Caddyfile, or something under supabase/volumes/.

Fix:

1. Run git log --oneline -10 in your repo. Find the last commit that didn't touch substrate files.
2. git revert <bad-commit-sha> — this creates a new commit that undoes the bad one.
3. git push — Hatchik redeploys with the substrate back to a known-good state.

Then go back to your AI tool and explicitly tell it: "AI_CONTEXT.md lists the substrate files. Don't edit any of them. Re-read AI_CONTEXT.md if you need to." That usually sorts it.

"My domain isn't showing my sandbox" (Launch tier)

If your Launch sandbox is on a custom domain and the site shows a Hatchik 404 or "tenant not found":

• Check the domain's DNS points to Cloudflare (the nameservers we gave you when you signed up). Use whatsmydns.net to confirm.
• Wait up to 24 hours after a DNS change for global propagation.
• Confirm the TLS certificate has issued — your domain should load on HTTPS without warnings. If you see a cert warning, the wildcard hasn't covered your domain yet (rare; usually self-heals within an hour).

If still broken after 24 hours, email us. Probably a Cloudflare-Caddy DNS-01 hiccup we can fix in a minute.

"My Stripe charges are showing as test mode"

Sandbox tier always runs Stripe in test mode. To accept real payments, upgrade to Launch and replace the test keys in your sandbox's .env with the live keys from your Stripe dashboard. Push and redeploy.

If you're on Launch and still seeing test charges, double-check your .env contains STRIPE_SECRET_KEY=sk_live_... (not sk_test_...) and that you've pushed since updating it.