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

# Troubleshooting

> Common issues and solutions for Container Apps and VPS Apps on RepoCloud

## General Issues

<AccordionGroup>
  <Accordion title="My application is stuck in 'Deploying' status">
    Initial deployments typically take 3–7 minutes for Container Apps and 2–5 minutes for VPS Apps. If the status does not change after 15 minutes:

    * **Container Apps**: Try deleting the instance and redeploying. If the issue persists, [open a support ticket](https://repocloud.io/support/new).
    * **VPS Apps**: The system automatically detects stuck deployments after 15 minutes and notifies the team. You will receive an email if the deployment is cancelled. You can redeploy from the marketplace.
  </Accordion>

  <Accordion title="My balance dropped to zero and my instances are paused">
    When your credit balance reaches zero, running instances are paused and billed at 25% of the normal rate. To resume:

    1. Go to [Billing](https://repocloud.io/billing) and add credit
    2. Instances resume automatically once your balance is positive
    3. Consider enabling **Auto-Recharge** to prevent future interruptions

    VPS instances have a **15-day grace period** at zero balance. If no credit is added within 15 days, the instance is permanently deleted. See [Billing](/manage/billing) for details.
  </Accordion>

  <Accordion title="I cannot deploy a VPS app">
    VPS deployment requires:

    * A minimum **\$1 deposit** (one-time, unlocks all VPS features)
    * A balance **greater than \$3** at deploy time

    Go to [Billing](https://repocloud.io/billing) to add credit.
  </Accordion>

  <Accordion title="I forgot my account password">
    Go to [repocloud.io/reset\_password](https://repocloud.io/reset_password) and enter your email. A reset link is sent to your inbox (valid for 1 hour, one-time use).
  </Accordion>
</AccordionGroup>

## Container App Issues

<AccordionGroup>
  <Accordion title="My app shows an error page after deployment">
    Some applications take a few minutes to fully initialize after the container starts. Wait 2–3 minutes and refresh the page. If the error persists:

    1. Check the **logs** from the manage page for error messages
    2. Verify your **environment variables** are configured correctly
    3. Try a **Rebuild / Update** to pull the latest Docker image
    4. If the app requires specific configuration (e.g., database credentials), ensure those are set in the environment variables
  </Accordion>

  <Accordion title="Custom domain SSL certificate is not issuing">
    SSL certificates for Container Apps are issued automatically via ACME DNS validation. If the certificate is not issuing:

    1. Verify both CNAME records (the routing CNAME and the `_acme-challenge` CNAME) are correctly configured at your DNS registrar
    2. Use [DNS Checker](https://dnschecker.org) to confirm the records are propagated
    3. Wait at least 30 minutes after DNS verification for certificate issuance
    4. Do **not** delete the `_acme-challenge` record — it is required for renewal
    5. If using multiple subdomains of the same root domain, consider using Cloudflare as your DNS provider
  </Accordion>

  <Accordion title="Environment variable changes are not taking effect">
    After saving environment variable changes, the container restarts automatically. This typically takes 3–7 minutes. If changes are not reflected:

    1. Wait for the restart to complete (watch the dashboard for the status to return to Online)
    2. Hard-refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
    3. Verify the variable names and values are exactly correct (no trailing spaces)
  </Accordion>

  <Accordion title="My app runs out of memory or disk">
    * If using **autoscaling** (the default): the platform automatically scales to a higher tier. Check the usage chart on the manage page to see which tier is being used.
    * If using a **fixed tier**: resize to a larger tier from the manage page. Consider switching to autoscaling if your resource needs are variable.
  </Accordion>
</AccordionGroup>

## VPS App Issues

<AccordionGroup>
  <Accordion title="I cannot SSH into my VPS">
    1. Verify the server status is **Online** on the manage page
    2. Use the correct IPv4 address shown in the **Access** section
    3. Connect as `root` on port 22: `ssh root@your-ipv4-address`
    4. Use the root password shown on the manage page, or the SSH key from deployment
    5. If you changed the root password and forgot it, use **Reset Root Password** on the manage page
    6. Try the **browser console** on the manage page as an alternative access method
  </Accordion>

  <Accordion title="VPS custom domain is not working">
    VPS custom domains use A records (not CNAME):

    1. Create an **A record** at your DNS registrar pointing to your VPS IPv4 address
    2. Enter the domain on the manage page under **Custom Domain**
    3. Wait for DNS propagation (can take up to 48 hours)
    4. If using **Cloudflare**, you will see a confirmation prompt — click Confirm to proceed
    5. SSL must be configured on the VPS itself (e.g., using Certbot or the application's built-in SSL)
  </Accordion>

  <Accordion title="Snapshot restore failed">
    Snapshot restores use ZFS rollback. If a restore fails:

    1. Check the job status on the manage page — the UI polls for completion
    2. If the job shows as FAILED, the VPS may be in an inconsistent state. Try power-cycling (power off, then power on)
    3. Note: restoring a snapshot taken at a smaller tier than the current tier may result in the disk reverting to the snapshot's size
    4. [Open a support ticket](https://repocloud.io/support/new) if the issue persists
  </Accordion>

  <Accordion title="My VPS is billing-paused and I cannot perform actions">
    When a VPS is system-paused at zero balance, most actions are locked (power on, reboot, resize, snapshot create/restore, console, SSH). Only delete is available. To unlock:

    1. Go to [Billing](https://repocloud.io/billing) and add credit
    2. The instance resumes automatically once your balance is positive
    3. All actions become available again
  </Accordion>

  <Accordion title="I cannot resize to a smaller tier">
    VPS disk allocation cannot be shrunk. You can only resize to a tier with equal or larger disk. For example, if you are on `s-2vcpu-4gb` (40 GB disk), you cannot downgrade to `s-1vcpu-2gb` (30 GB disk). This is a limitation of the underlying storage architecture.
  </Accordion>
</AccordionGroup>

## API / MCP Issues

<AccordionGroup>
  <Accordion title="API returns 401 Unauthorized">
    * Verify your API key starts with `rcmcp_`
    * Check that the key is active in the [API / MCP tab](https://repocloud.io/mcp)
    * Ensure the `Authorization` header format is exactly: `Bearer rcmcp_your_key_here`
    * If the key was revoked, create a new one
  </Accordion>

  <Accordion title="API returns 402 when deploying">
    Your balance must be greater than \$3 to deploy through the API. Go to [Billing](https://repocloud.io/billing) to add credit.
  </Accordion>

  <Accordion title="API returns 429 Too Many Requests">
    You have exceeded the rate limit (60 requests per minute, or 5 deploys per hour). The `Retry-After` header indicates how long to wait.
  </Accordion>
</AccordionGroup>

## Still Need Help?

If your issue is not covered here, [open a support ticket](https://repocloud.io/support/new) from the Support tab in your dashboard. Include:

* The application name and instance ID
* Steps to reproduce the issue
* Any error messages you see
* Screenshots if applicable