Troubleshooting

404 on every page except the home page

Cause: mod_rewrite isn't enabled, or AllowOverride All isn't set for htdocs, so .htaccess is ignored and requests never reach index.php.

Fix: In your Apache config (httpd.conf or httpd-vhosts.conf), make sure the <Directory "htdocs"> block has AllowOverride All, and that mod_rewrite is loaded (uncomment LoadModule rewrite_module modules/mod_rewrite.so). Restart Apache afterwards.

Warning: Undefined variable $pdo / Call to a member function query() on null

Cause: A page file queries the database directly ($pdo->query(...) / $pdo->prepare(...)) without declaring global $pdo; first. Because page files are required from inside the route() function in app/router.php, they run in that function's local scope, where the global $pdo isn't automatically visible.

Fix: Add global $pdo; right after the require_once __DIR__ . '/../app/bootstrap.php'; line in the affected page. See Architecture for more detail.

403 Forbidden when opening /pages/... or /app/... directly

This is expected and intentional — see Architecture, section "Defense against direct file access". Pages must be accessed through their route (e.g. /dashboard), not their file path.

"Direct access to this file is not allowed."

Same cause as above, just triggered by the PHP-level check (APP_ROUTED constant) instead of the .htaccess rule. Always navigate via the routes defined in config/routes.php.

Renamed the project folder and now nothing works

This should not happen — the app detects its own subfolder automatically via BASE_PATH (see Architecture). If it does happen, check:

• That you're not using any hardcoded /path links anywhere outside the url() helper.
• That .htaccess is present and being read (see the 404 section above) — the rewrite rule itself is relative and does not need to know the folder name.

"Database connection failed: ..."

Cause: Wrong credentials or database name in config/database.php, or MySQL isn't running.

Fix: Double-check $DB_HOST, $DB_NAME, $DB_USER, $DB_PASS in config/database.php, and confirm the database exists (import sql/database.sql if you haven't yet) and that MySQL is started in XAMPP.

Can't log in as admin / /admin/users shows 403

Cause: No account with the admin role exists yet, or your account still has the pending role.

Fix: Follow the "Create the first administrator" step in Installation — generate a password hash via tools/generate_hash.php and insert the account manually with role = 'admin'.

New users can't get past the dashboard

This is expected: new self-registered accounts have the pending role, which has no access beyond a placeholder message on /dashboard. An administrator has to open /admin/users, edit the account, and assign a real role. See Admin Guide.