Common issues

Match the error you see to a section below, then check the cause and fix. Keep the relevant server log entry when reporting a problem.

Root URL returns 403

Before the first publish, open https://example.com/_studio/, using your domain. Complete installation and publish the site, then check the root URL.

Installer says "cannot reach the server"

The installer loaded but cannot reach the API. Check that your host runs PHP 8.2+ and executes .php files. On Apache, enable mod_rewrite, set AllowOverride All and restart Apache.

Blank page or 500 error after installation

Check the hosting error log for the PHP error. Confirm PHP 8.2+ and the extensions listed in Requirements.

Permission errors during AI generation

Check that the web-server user can write to _studio/data, _studio/preview, _studio/revisions and assets. Ask your host to fix ownership or permissions. A mode such as 755 does not grant writes to every user.

AI not responding

For built-in Chat, verify your provider configuration in Settings. Installation can skip this setup; it is required only when you choose built-in generation. 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 leaves missing CSS or JavaScript

Symptoms: Only some pages or assets appear, the preview is unstyled, or generation stops before the requested work is complete.

Check the reported result first:

• Output limit reached: The model ran out of allowed output. Usable changes are marked partial; a limit reached before website changes are returned is an error. Check Settings → AI Provider for the configured ceiling and effective full-generation limit. Increase the ceiling if the model supports more, choose a model with a larger output limit, or split the work into smaller requests. Review what exists, then ask the AI to finish the missing pages or assets.
• Generation hangs or the server terminates PHP: Check the hosting error log and PHP execution timeout. 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.

On Laravel Forge, the timeout setting is under Server → PHP → Max Execution Time. Raising a server timeout does not increase a model's output limit.

AI returns an empty response

VoxelSite reports an empty response as an error. A provider can report token usage without returning visible content, so usage alone does not mean generation succeeded. Retry with a smaller request or another model, and check the effective output limit in Settings. If the error says the output limit was reached, increase your ceiling only if the selected model supports more output.

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.

Do not use $uri.php as a middle argument in try_files. It can expose PHP source instead of executing it. Use the @cleanurls rewrite above.

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;

Nginx then passes the 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: Older builds need an Nginx rewrite to reach the Agent API router. Current builds include a Studio fallback. Check the installed version and the Nginx route configuration.

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 HTTP 503 with exec_unavailable or php_cli_unavailable. Other Agent API endpoints still work.

Prompt execution needs both PHP's exec() function and a working PHP command-line executable to start its background worker. VoxelSite checks these before creating a conversation or queued job.

If your hosting plan cannot provide both, Agent prompt execution is unavailable on that plan. The other Agent API endpoints remain available.

Tip: The OpenAPI schema's x-capabilities.prompt_execution.available flag checks whether exec() is enabled. It does not verify PHP CLI; that check happens when you submit a prompt.

See Agent API → Prompt Execution for the full async flow and requirements.

Site changes fail or the result is unconfirmed

These recovery steps apply to Site in VoxelSite 1.32.0 or later.

The website changed after review, or the review expired: Build and review a new plan. Reviews expire after 30 minutes. Site refuses to apply stale or partly invalid plans.

References need review: Open the listed source files in Editor. Site cannot resolve every dynamic PHP link or include. URL changes, moves and deletion can stop before writing when references remain unresolved.

Apply result unconfirmed: Click Check result before retrying. A broken connection can hide a completed operation. Site checks the saved server result without submitting the edits again.

Some changes remain: Review the listed files and recovery snapshot. Website changes and resets stay blocked until a snapshot restore succeeds. Notes, account and settings remain available.

Before restoring, check the snapshot and selected domain. Draft restoration changes private pages and mutable assets. Published restoration changes the live site while preserving newer draft work. A combined restore changes both. Older archives may not support every domain.

Open Designs → History and match the recovery snapshot ID to its History row. Restore that snapshot. If restoration fails, keep the error and snapshot ID. Ask your host to check write access to the reported files, then retry. A successful restore records the chosen snapshot as the recovery action; it does not change the original failure report.

Private workspace activation fails

Check the installation URL, HTTPS and web-server protection for _studio/preview/ and retained private directories. On Nginx, apply the private-directory rules. Activation must be able to reach its own public control URL and confirm private paths are denied. Fix the cause and retry; do not bypass the check or expose the draft.

If source compatibility or ownership fails, keep the diagnostics. A customized legacy file may need review before it can enter the managed workspace. Preserve published files and the migration record.

External connection or retained operation fails

Check Settings → Connections for authentication, successful use and permission failures. A copied configuration is not connection evidence. Verify the endpoint, credential audience and current bound account. Existing REST keys may need Connect account.

For an interrupted write, read its retained status using the same operation ID before starting another request. Continue with its returned checkpoint, or use owner recovery if the original actor lost access. See Studio MCP troubleshooting.

An old snapshot cannot restore publicly

A published or combined restore refuses an archive whose public target includes private authoring memory.json or design-intelligence.json. The archive remains inspectable, and a compatible draft-only restore can still be used. Review the restored draft and publish a safe current candidate instead.

Publication asks for Actions Bar migration

Review the legacy values shown under Actions Bar settings and save them to the private draft. Publication does not silently replace those values with defaults. Then prepare a new publication review.

AI Router uses the default model

This means routing could not choose a usable route. Editing can continue. Check the TypeSafe key and both model choices in Settings → AI Router. A provider change requires matching model choices. A service outage, uncertain result or oversized focused context can also cause fallback. See Router setup and fallback behavior.