Troubleshooting

Fixes for the issues operators hit most often. Start with the symptom that matches, and when in doubt, read storage/logs/php-error.log — it records the precise underlying error.

Dashboard error: Database.php line 41

What line 41 actually is

Line 41 of the PDO database wrapper (Database.php) is the query-execute step — the point where a prepared statement is run against MySQL. The raw symptom is an uncaught PDOException thrown at execution time. BlockID now catches that exception and shows a friendly error page instead of leaking a stack trace, so seeing "line 41" simply tells you the database call failed — not that the file is broken.

Causes to check, in order

1. Config missing or incomplete

   The most frequent cause: config/config.php is absent or missing values, so the DB_* constants (DB_HOST, DB_NAME, DB_USER, DB_PASS) are undefined. Re-run /install/index.php or confirm the file exists and is complete.

2. Wrong host / name / user / password

   The constants exist but don't match your MySQL server. Verify the database host, database name, username, and password are exactly right (watch for trailing spaces and the correct host — localhost vs 127.0.0.1 vs a socket).

3. Schema or migration not imported

   The connection works but a table the query needs doesn't exist. Import the schema / run the migrations so every required table is present. The log will name the missing table.

4. Shared-hosting "unbuffered queries" (HY000/2014)

   On some shared hosts you'll see Cannot execute queries while other unbuffered queries are active (HY000/2014). This happens when a previous result set wasn't fully read. BlockID fixes it by using buffered queries (so results are fetched fully and the connection is ready for the next statement).

5. Dashboard loaded before install completed

   If you opened /dashboard.php before finishing the installer, there's no valid config or schema yet. Complete /install/index.php first, then return to the dashboard.

6. Include path wrong after moving the marketing site to root

   Since the marketing site now lives at the project root, a stale include path can prevent config/config.php or core files from loading. Confirm includes resolve from the new root layout.

The fix is already implemented

BlockID ships with hardening around exactly this failure:

• Buffered queries — avoids the HY000/2014 unbuffered-query error on shared hosting.
• A 5-second connection timeout — fails fast instead of hanging when the DB is unreachable.
• Typed exceptions that route to friendly pages: /errors/database.html (connection/query failures) and /errors/config-missing.html (no/invalid config).

tail -n 50 storage/logs/php-error.log

Blank page

A completely blank page in production usually means an error occurred but display_errors is off (as it should be in production). Don't turn it on for live traffic — instead read the log:

tail -n 80 storage/logs/php-error.log

The log will show the fatal error. If it's database-related, jump to Database.php line 41 above.

403 on /config or /core

This is expected and correct. /config, /core, and /storage are deliberately denied over HTTP to keep configuration, core code, and logs off the public web. A 403 here means your protection is working. If these directories are not returning 403, fix your server config (see Deployment).

CSRF 403 on forms

A 403 when submitting a form (including Sign Out) usually means the CSRF token expired or cookies are disabled.

• Reload the page to get a fresh token, then resubmit.
• Enable cookies for the site — the token is tied to your session.
• If you left a tab open a long time, the session may have ended; sign in again.

API 401 / 403

API 429 (rate limit)

You've exceeded 120 requests per minute for the token. Slow down, add exponential backoff, and batch where possible. The limit is per token, so splitting unrelated workloads across separate tokens can help.

Login lockout

Repeated failed sign-ins can trigger a temporary lockout to slow brute-force attempts. Wait for the lockout window to pass and try again with the correct credentials. If you've forgotten the password, use your account-recovery process. Persistent lockouts may indicate someone is guessing the password — review the audit log.

Theme not persisting

The dark/light choice is stored in the browser. If it doesn't stick:

• Allow cookies and local storage for the site — private/incognito windows and some privacy settings block localStorage.
• If localStorage is unavailable, BlockID falls back to your OS preference each visit rather than remembering a manual choice.
• Clearing site data resets the preference to default.

/install still accessible

rm -rf /var/www/blockid/install

Then reload /install/index.php and confirm it returns 404.

Still stuck? Re-check Deployment and Security, and confirm the exact error in storage/logs/php-error.log.