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

# Troubleshooting

> Common issues across VMs, apps, billing, and account — and how to fix them.

This page is the cross-cutting "where do I start when something's wrong" guide. For app-specific issues, see the app's marketplace page (e.g. [OpenClaw](/marketplace/openclaw)).

## VMs

<AccordionGroup>
  <Accordion title="VM stuck in 'provisioning'">
    Provisioning typically finishes in 60–120 seconds. If it sits in `provisioning` for more than 10 minutes, Suji marks it `error` and partially cleans up.

    **Fix:** delete the failed VM and create a new one. If it happens repeatedly, file a support ticket — usually a transient cloud-provider issue.
  </Accordion>

  <Accordion title="VM shows 'error' status">
    Causes:

    * Out-of-memory kill of a critical process
    * Underlying disk issue
    * Network blip during a state transition

    **Fix:** click **Restart** from the instance detail page. Check **Logs** for the cause. If the VM has been getting OOM'd, [resize](/manage-vm/resize) up.
  </Accordion>

  <Accordion title="VM won't start after being stopped">
    Most common: **credit balance is €0**. The dashboard shows a banner explaining; top up to resume. See [Grace period](/billing/grace-period).

    Other causes: ongoing maintenance in the region (rare), or you're trying to start while it's still in a transitional state — wait 30 s and retry.
  </Accordion>

  <Accordion title="VM is slow or unresponsive">
    1. Open the **Metrics** tab — sustained CPU at 100% or memory at the cap means you've outgrown the size.
    2. [Resize up](/manage-vm/resize). Reboot takes \~60 s.
    3. Check **Logs** for crash-restart loops in any app (cycles of "starting → exited → starting").
  </Accordion>

  <Accordion title="Can't SSH into the VM">
    Check, in order:

    1. **SSH key registered?** Settings → SSH Keys before VM creation.
    2. **Right user?** `ssh root@<public-ip>`.
    3. **Firewall?** The default rules allow SSH from anywhere. If you replaced it with a restricted rule, your current IP must be in the source list.
    4. **VM status?** Must be `running`. Stopped VMs aren't reachable.

    If SSH still fails, use the dashboard's **Terminal** tab as a fallback.
  </Accordion>
</AccordionGroup>

## Apps

<AccordionGroup>
  <Accordion title="App stuck in 'installing'">
    Usually means the Docker image is taking a long time to pull (large image, slow network). Wait 2–3 minutes. If it's still `installing` after that, check the install's Logs tab — there's usually a `Pulling`, `Error: denied`, or `manifest unknown` message indicating the cause.
  </Accordion>

  <Accordion title="App is 'failed' — what now?">
    The install row has a `last_error` field with the reason. Common ones:

    * **"image denied / unauthorized"** — the image isn't public; we don't support private registries yet.
    * **"port in use"** — rare; redeploy resolves it.
    * **"docker compose up failed"** with an EACCES — volume ownership issue; usually fixes itself on the next upgrade. If not, open a support ticket.

    Try a redeploy (Install detail page → Restart, or Upgrade). If still failing, the Logs tab usually has the smoking gun.
  </Accordion>

  <Accordion title="App's `*.suji.fr` URL returns 502 Bad Gateway">
    Cloudflare can't reach the app inside your VM. Check, in order:

    1. **Is the container running?** Dashboard → Logs tab for that install. If it's crashing on startup, the logs say why.
    2. **Is the app actually listening on its declared port?** Most app-specific bugs are here — see the app's marketplace page for app-specific debugging (e.g. [OpenClaw's bind-mode setting](/marketplace/openclaw#troubleshooting)).
    3. **Cloudflare propagation** — right after install or subdomain change, give it 30 s.
  </Accordion>

  <Accordion title="Webhook isn't reaching the app">
    1. Confirm the third-party service is configured with the right URL (`https://<install-subdomain>.suji.fr/...`).
    2. Open Logs for the install, send a test webhook. If nothing appears in the logs, the request didn't reach the app — DNS / Cloudflare issue.
    3. If you see the request hit the app but get a 4xx/5xx, the app rejected it; the body of the response or the next few log lines explain why.
  </Accordion>
</AccordionGroup>

## Billing & credits

<AccordionGroup>
  <Accordion title="My VMs are gone — credit went to zero">
    Expected behavior at €0: each VM is terminated, with an automatic snapshot kept for **7 days**. Top up from **Billing → Top up**, then restore from the termination snapshot to get your VM back. If your VM shows `suspended` instead (auto-recharge card failure), fix the card and click **Resume**. See [Grace period](/billing/grace-period).
  </Accordion>

  <Accordion title="Auto-recharge failed">
    The card was declined. You'll see a "card declined" email and a banner in the dashboard. Fix the card in **Billing → Payment methods** — Stripe automatically retries. If retries also fail, you fall into the standard grace period.
  </Accordion>

  <Accordion title="Charge appears in Stripe but credit didn't land">
    Webhook delay (rare). Refresh the dashboard after 30 s. If the credit still doesn't show, file a ticket with your Stripe payment reference — we can reconcile manually.
  </Accordion>

  <Accordion title="Invoice missing VAT number / company details">
    Set them once in **Billing → Profile**. Future invoices pick them up automatically. Old invoices can be re-issued with updated details on request.
  </Accordion>
</AccordionGroup>

## Account

<AccordionGroup>
  <Accordion title="Forgot password">
    Go to [app.suji.fr/forgot-password](https://app.suji.fr/forgot-password) and enter your email. The reset link is valid for 1 hour.
  </Accordion>

  <Accordion title="Verification email not received">
    1. Check spam.
    2. Dashboard → **Resend verification email**.
    3. Confirm the email address you registered with.
    4. Rate-limited to 5 resends per hour.
  </Accordion>

  <Accordion title="2FA code rejected">
    1. Your authenticator and our server may have time drift — re-sync your authenticator's clock.
    2. If you're locked out, email `support@suji.fr` from the address on the account — we can verify identity and reset 2FA.
  </Accordion>

  <Accordion title="Lost access to a colleague's seat">
    Org owner → **Settings → Members** → remove the old member and invite a new one. The org's resources are unaffected; only access changes.
  </Accordion>
</AccordionGroup>

## Network / firewall

<AccordionGroup>
  <Accordion title="A port I opened isn't reachable">
    1. Is the firewall rule for the correct VM and direction?
    2. Is the app actually listening on that port inside the VM? `ss -tlnp` from the host terminal confirms.
    3. Is the app bound to `0.0.0.0` (not `127.0.0.1`)? Apps that default to loopback won't accept external connections even if the firewall is wide open.
    4. Is the port in the [provider-blocked list](/manage-vm/firewall#provider-blocked-ports) (25 / 465 outbound)?
  </Accordion>

  <Accordion title="Mail isn't sending">
    Outbound TCP 25 and 465 are blocked at the network layer. Use port 587 with STARTTLS or an HTTP-based provider (SendGrid / Postmark / Mailgun / Resend). A firewall rule won't unblock those ports.
  </Accordion>
</AccordionGroup>

## Still stuck

Open a support ticket from the dashboard with:

* Your account email and organization name.
* Instance ID (`inst_…`) and install ID (`install_…`) if applicable.
* A short description of what you expected vs what happened.
* The last 20–30 lines of relevant logs.
* A screenshot if it's a UI issue.

The clearer the report, the faster we can help.