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

# Troubleshooting

> Solutions for common issues in Hiveku Builder

## Deployment Issues

<AccordionGroup>
  <Accordion title="Deployment failed with a build error">
    **Symptoms:** Deployment status shows "failed" with a build error in the logs.

    **Solutions:**

    1. Check **Settings > Deployment History** and expand the failed deployment to read the error message
    2. Common causes:
       * Syntax errors in JavaScript/TypeScript files
       * Missing dependencies (run `npm install` in the terminal)
       * Invalid `package.json` or build script
    3. Fix the issue in the code editor and deploy again
    4. If the error is unclear, switch to **Debug** mode in the AI chat and paste the error message

    <Info>A failed deployment never affects your live site. The previous successful version remains online.</Info>
  </Accordion>

  <Accordion title="Site shows a blank white page after deploying">
    **Symptoms:** Deployment succeeded but the site shows nothing.

    **Solutions:**

    1. Open browser DevTools (F12) and check the **Console** tab for JavaScript errors
    2. Verify your `index.html` or entry point exists in the project files
    3. For React/Next.js apps, ensure the root component renders correctly
    4. Check the **Hosting** dashboard log viewer for server-side errors
    5. Ask the AI in Debug mode: "My site shows a blank page after deploying -- diagnose the issue"
  </Accordion>

  <Accordion title="Custom domain shows SSL error or redirect loop">
    **Symptoms:** Browser shows "Your connection is not private" or the page keeps redirecting.

    **Solutions:**

    1. **DNS not propagated yet** -- wait 15-30 minutes after adding your CNAME record, then click **Verify DNS Configuration** in Settings
    2. **Cloudflare users** -- set your CNAME proxy status to **DNS only (gray cloud)**, not Proxied. If you must use Cloudflare proxy, set SSL/TLS mode to **Full (strict)**
    3. Check that your CNAME record points to the exact distribution address shown in the domain setup wizard
    4. Use [dnschecker.org](https://dnschecker.org) to verify DNS propagation globally
  </Accordion>
</AccordionGroup>

## AI Assistant Issues

<AccordionGroup>
  <Accordion title="AI says credits are exhausted">
    **Symptoms:** The AI won't make changes and shows a credits warning.

    **Solutions:**

    1. Credits reset on the 1st of each month automatically
    2. Switch to **Hiveku Mini** (free on all plans) for basic tasks
    3. Ask your account Owner/Admin to upgrade the plan for more credits
    4. Connect a BYOK Anthropic API key in **Settings > AI Credits** to bypass credits entirely
  </Accordion>

  <Accordion title="AI is slow or not responding">
    **Symptoms:** Messages take a long time or the stream hangs.

    **Solutions:**

    1. Try switching to a different model tier (Mini is fastest)
    2. Use `/compact` to condense a long conversation -- this frees up context space
    3. Start a new session with `/clear` if the conversation has become very long
    4. Set reasoning effort to **Low** for simple tasks
    5. Check your internet connection
  </Accordion>

  <Accordion title="AI made changes I don't want">
    **Symptoms:** The AI edited files incorrectly or broke something.

    **Solutions:**

    1. Open the affected file in the code editor
    2. Click the **History** icon (clock) in the toolbar
    3. Browse the version list and click **Restore** on the version before the AI's changes
    4. Save the restored file with Ctrl+S / Cmd+S

    <Tip>For an entire-project rollback (not just one file), use **[Checkpoints](/editor/checkpoints)** -- Hiveku creates one automatically before each AI session and you can also create them manually before a risky change.</Tip>
  </Accordion>
</AccordionGroup>

## Editor Issues

<AccordionGroup>
  <Accordion title="Preview is not updating after I save">
    **Symptoms:** Changes in the editor don't appear in the preview pane.

    **Solutions:**

    1. Make sure you saved the file (Ctrl+S / Cmd+S) -- look for the dot indicator on the tab to disappear
    2. Try refreshing the preview manually using the refresh button in the preview toolbar
    3. For container-based projects, the hot reload may take a few seconds
    4. Check the browser console for JavaScript errors that might prevent rendering
  </Accordion>

  <Accordion title="File upload failed or file is missing">
    **Symptoms:** Uploaded files don't appear in the file tree.

    **Solutions:**

    1. Binary files (images, videos) are stored as assets -- check the asset manager
    2. Make sure the file isn't too large for your plan's storage limit
    3. Try uploading again by dragging the file onto a specific folder in the file tree
    4. Check **Settings > Resource Usage** to verify you haven't hit your storage limit
  </Accordion>
</AccordionGroup>

## GitHub Issues

<AccordionGroup>
  <Accordion title="Push to GitHub failed">
    **Symptoms:** Committing or pushing changes shows an error.

    **Solutions:**

    1. Verify your GitHub connection in **Settings > GitHub** -- reconnect if the token has expired
    2. Check that the Hiveku GitHub App still has access to the target repository
    3. If there are conflicts, pull the latest changes first, resolve conflicts, then push again
    4. Make sure the repository hasn't been deleted or transferred on GitHub
  </Accordion>

  <Accordion title="Pull overwrote my local changes">
    **Symptoms:** Files you edited were replaced by the GitHub version.

    **Solutions:**

    1. Check **version history** for the affected files -- your pre-pull versions should be saved as snapshots
    2. Restore the version you need from history
    3. In the future, always commit your local changes before pulling

    <Warning>Pulling changes overwrites local files with the GitHub version. Always commit first if you have unsaved work.</Warning>
  </Accordion>
</AccordionGroup>

## Database Issues

<AccordionGroup>
  <Accordion title="Database connection failed">
    **Symptoms:** Your app can't connect to the database, or queries return errors.

    **Solutions:**

    1. Verify the database is provisioned in **Project Settings > Database**
    2. Check that your environment variables include the correct `DATABASE_URL`
    3. For BYOD (Bring Your Own Database), verify the connection string is correct and the database allows connections from Hiveku's IP range
    4. Check the Hosting dashboard log viewer for connection error details
  </Accordion>

  <Accordion title="How do I restore my database from a backup?">
    Go to **Project Settings > Database > Backups** and find the backup you want. Click **Restore** to replace the current database with that backup.

    <Warning>Restoring a backup replaces all current data. Create a **[Checkpoint](/editor/checkpoints)** first if you want to preserve the current state.</Warning>
  </Accordion>
</AccordionGroup>