Installation Errors
Bearbeitung vorschlagenDiagnose PHP, dependency, database, URL, and asset failures without repeatedly reinstalling an existing store.
On this pageJump to a section
Identify the failing layer, collect useful evidence, and choose a safe repair instead of deleting data or secrets.
Capture the exact failure
Record the URL/command, timestamp, operating system, PHP version, installation method, and the first useful error. A blank page, a database rejection, and missing CSS are different problems. If the installer already completed, treat the issue as a runtime problem until evidence says otherwise.
php -v
php --ini
php -mUse the PHP binary that actually runs the app. The browser wizard and terminal can use different PHP versions. Redact credentials, tokens, personal data, and private filesystem information before sharing logs.
PHP and dependencies
| Symptom | Check |
|---|---|
| PHP 8.3 requirement fails | Select a supported CLI and web PHP version; verify both rather than only the hosting dropdown. |
| could not find driver | Enable pdo_mysql for the actual php.ini and restart the web PHP service. |
| DOMDocument missing | Enable DOM/XML support for that PHP version. |
| vendor/autoload.php missing | Use the prepared release correctly or run composer install in a source checkout. |
| npm engine/build failure | Check the lockfile’s Node requirement; deployed Vite requires ^20.19.0 or >=22.12.0. |
Do not use –ignore-platform-reqs to conceal an unsupported production PHP runtime. Fix the missing requirement or use a supported environment.
Database connection or already-used database
For connection refused, confirm the database service, host, and port. For access denied, check the database user and privileges. For a non-empty/already-used database, create a different empty database for a fresh install. Do not drop tables from an existing shop to satisfy the installer.
Keep host, database name, and table prefix distinct. A successful connection to the wrong database is still wrong. Review the current .env privately and use the supported installer options.
Missing assets, images, or styles
A source checkout does not include the generated production build. After locked dependencies install successfully, run:
npm run build
php artisan wento:theme-publishCheck public/build/manifest.json and the published theme assets. If Vite development mode is expected, ensure the dev server is running; if it is stopped, do not leave the app pointing to an obsolete development URL. For uploaded images, verify storage permissions and the supported storage link.
php artisan storage:linkURL, port, and permissions
Use the helper’s actual URL; do not open the HTML file with file://. If a port is occupied, choose another and align APP_URL and session/stateful-domain settings. For web-server 404s, check document root and rewrite configuration before changing application routes.
For permission errors, fix ownership and the required writable directories such as storage and bootstrap/cache. Avoid granting global 777 permissions. Read the application/web-server log for the underlying error rather than turning public debug on.
Do not use destructive fixes for normal errors
Do not remove storage/app/installed.lock, run migrate:fresh, reimport the install schema, or regenerate an existing APP_KEY as generic troubleshooting. Back up first and identify the real failure.
If you need help, send sanitized steps to reproduce, version, timestamp, exact error, and the install method. Do not send .env contents or a database export through a public support channel.
Continue learning
System Requirements · Installing WentoCart · Backups & Maintenance