Common Issues — VoxelSite Troubleshooting Guide

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.

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

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.

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:

fastcgi_param HTTP_AUTHORIZATION $http_authorization;

This tells Nginx to pass the Authorization header to PHP as $_SERVER['HTTP_AUTHORIZATION'].See Nginx Configuration for the complete config example.

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:

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

See Nginx Configuration for where to place this in the full config.

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:

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
VPS / Managed Server (Forge, RunCloud, Ploi): Edit your php.ini to remove exec from disable_functions, then restart PHP-FPM
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

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.

Documentation Index