Common Issues

Quick fixes for the most frequently reported issues.

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.

Installer says "Cannot reach the server"

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.

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.

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).

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.

See Supported AI providers for where to get an API key for each provider.

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). See Requirements → PHP execution timeout for instructions per server type.

This is the #1 support issue. On Laravel Forge, the fix is: Server → PHP tab → set Max Execution Time to 600.

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:

location / {
    try_files $uri $uri/ @cleanurls;
}

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

See Nginx Configuration for the complete config and security blocks.

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.