Troubleshooting

Installer Does Not Open

Confirm the ZIP was extracted into the domain root, install/index.php exists, PHP is enabled, and the packaged .htaccess was uploaded. If the app loads a blank page, check PHP error logs and Apache rewrite support.

Database Connection Fails

Verify database host, database name, username, password, and user privileges. The installer needs permission to create tables, insert seed data, and apply migrations.

API Routes Return 404

Confirm Apache rewrite rules are enabled and /api/v1/* routes to the backend. On local development, verify the backend server is running and VITE_API_BASE_URL points to the correct API base URL.

Login Fails After Installation

Use the administrator email and password entered in the installer. If login still fails, check that backend/.env exists, JWT_SECRET is set, and the users table was seeded or updated during installation.

CORS Errors

In production, set CORS_ORIGINS to the exact frontend origin. For same-domain packaged installs, API and frontend should normally share the same origin.

Missing Sidebar Items

A module may be disabled, blocked by the user's role profile, or hidden because the user lacks the required permission. Review Settings, active modules, role permissions, and the user's assigned role.

Migration Errors

Apply migrations in timestamp order. If a migration partially ran, inspect schema_migrations, repair the database state, and rerun the migration command or installer only after confirming the schema is consistent.