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

# Common Issues — VoxelSite Troubleshooting Guide

> Quick fixes for the most frequently reported VoxelSite issues, including blank pages, missing CSS, Nginx routing, AI errors, and Agent API problems.

Quick fixes for the most frequently reported issues. If you can't find a solution here, see [Getting Support](/troubleshooting/getting-support).

<AccordionGroup>
  <Accordion title="Root URL returns 403">
    This is expected before your first site is published. Go to `yourdomain.com/_studio/` to access the installer and Studio. The root URL will work after you publish your first site.
  </Accordion>

  <Accordion title="Installer says &#x22;Cannot reach the server&#x22;">
    The installer UI loaded but cannot reach the API. Verify PHP 8.2+ is running and `.php` files are processed correctly. On Apache: enable `mod_rewrite` and set `AllowOverride All`, then restart Apache.
  </Accordion>

  <Accordion title="Blank page or 500 error after installation">
    Check that PHP 8.2+ is active and the required extensions are installed. Check your hosting error log for specific PHP errors.
  </Accordion>

  <Accordion title="Permission errors during AI generation">
    Make sure `_studio/data`, `_studio/preview`, `_studio/revisions`, and `assets` directories are writable by the web server (755 or 775 on most hosts).
  </Accordion>

  <Accordion title="AI not responding">
    Verify your API key is correct in **Settings**. Check that cURL is enabled and your server can make outbound HTTPS requests. Some hosting providers block outgoing connections on shared hosting plans.
  </Accordion>

  <Accordion title="Generation produces only a few files — missing CSS/JS">
    **Symptoms:** The AI generates 3–5 files (header, nav, footer, index), but the remaining pages and all CSS/JS files are missing. The preview shows unstyled text. The chat may show "Generation in progress..." indefinitely.

    **Cause:** The server's PHP execution timeout is too low. AI site generation takes 2–4 minutes. If the server kills the PHP process before it finishes, only the files written so far are saved.

    **Fix:** Set `max_execution_time`, `request_terminate_timeout`, and `fastcgi_read_timeout` to at least `600` (10 minutes).

    <Tip>
      This is the #1 support issue. On **Laravel Forge**, the fix is: **Server → PHP tab → set Max Execution Time to `600`**.
    </Tip>
  </Accordion>

  <Accordion title="Pages show the homepage on Nginx (Forge, RunCloud, Ploi)">
    **Symptoms:** The homepage works fine, but visiting `/about` or `/contact` shows the homepage content instead of the correct page. The PHP files exist on the server.

    **Cause:** VoxelSite ships `.htaccess` for Apache clean URL routing (`/about` → `about.php`). Nginx ignores `.htaccess` entirely, and its default `try_files` rule falls back to `index.php` when it can't find a file named `about` (without the `.php` extension).

    **Fix:** Add a named location rewrite to your Nginx config:

    ```nginx theme={null}
    location / {
        try_files $uri $uri/ @cleanurls;
    }

    location @cleanurls {
        rewrite ^/(.+)$ /$1.php last;
    }
    ```

    See [Nginx Configuration](/troubleshooting/nginx-configuration) for the complete config and security blocks.

    <Warning>
      **Common mistake:** Do not use `$uri.php` as a middle argument in `try_files`. This serves the PHP file as raw text (downloads the source code) instead of processing it through PHP-FPM. The `@cleanurls` rewrite approach does a proper internal redirect.
    </Warning>
  </Accordion>

  <Accordion title="Agent API returns 401 on Nginx">
    **Symptoms:** Agent API requests return `{"error":{"code":"no_header","message":"Missing Authorization header..."}}` even with a valid API key. The same key works on Apache or via `php -S`.

    **Cause:** Nginx strips the `Authorization` header before forwarding requests to PHP-FPM. The Agent API uses Bearer token authentication, which relies on this header.

    **Fix:** Add this line inside your `location ~ \.php$` block:

    ```nginx theme={null}
    fastcgi_param HTTP_AUTHORIZATION $http_authorization;
    ```

    This tells Nginx to pass the `Authorization` header to PHP as `$_SERVER['HTTP_AUTHORIZATION']`.

    See [Nginx Configuration](/troubleshooting/nginx-configuration) for the complete config example.
  </Accordion>

  <Accordion title="Agent API returns 404 on Nginx">
    **Symptoms:** All Agent API requests (`/_studio/api/agent/v1/pages`, etc.) return 404. The Studio UI and clean URLs work fine.

    **Cause:** On older VoxelSite versions, the Agent API relies on an Nginx rewrite rule to route requests to `router.php`. Current versions include a Studio router fallback that handles this automatically, so this issue typically means you are running an older build.

    **Fix:** Update VoxelSite to the latest version (**Settings → Update**). If you cannot update, add this location block **before** your `location ~ \.php$` block:

    ```nginx theme={null}
    location ~ ^/_studio/api/agent/v1/(?!.*\.php)(.*)$ {
        rewrite ^/_studio/api/agent/v1/(.*)$ /_studio/api/agent/v1/router.php?_path=$1&$args last;
    }
    ```

    See [Nginx Configuration](/troubleshooting/nginx-configuration) for where to place this in the full config.
  </Accordion>

  <Accordion title="Agent API prompt execution returns 503">
    **Symptoms:** `POST /_studio/api/agent/v1/prompt` returns `{"error":{"code":"exec_unavailable","message":"..."}}`. Other Agent API endpoints work fine.

    **Cause:** Prompt execution requires PHP's `exec()` function to spawn a background worker process. Many shared hosting providers disable `exec()` in their `php.ini` (`disable_functions = exec, ...`) for security reasons.

    **Fix:**

    1. **Check if `exec()` is available:** Create a temporary PHP file with `<?php var_dump(function_exists('exec'));` and visit it in your browser, or run `php -r "var_dump(function_exists('exec'));"` from the command line
    2. **VPS / Managed Server (Forge, RunCloud, Ploi):** Edit your `php.ini` to remove `exec` from `disable_functions`, then restart PHP-FPM
    3. **Shared hosting:** Contact your hosting provider to whitelist `exec()`. If they cannot, prompt execution is not available on your plan — the rest of the Agent API still works

    <Tip>
      The OpenAPI schema at `/_studio/api/agent/v1/schema` includes a `x-capabilities.prompt_execution.available` flag that agents can check before attempting to use prompt execution.
    </Tip>
  </Accordion>
</AccordionGroup>