Troubleshooting

Common errors

Error: database connection failed

Symptom: the page reports "database connection failed"

• Resolution:
• Check permissions on the data/ directory: chmod 755 data/
• Confirm neurova.db exists and is writable
• Check that the PHP SQLite extension is installed

Error: cannot sign in to the admin console

Symptom: sign-in fails even with the correct username and password

• Resolution:
• Check that cookies are enabled in the browser
• Check permissions on the session directory
• Clear browser cache and cookies
• Look at the error logs under logs/

Error: the API returns 401 Unauthorized

Symptom: API requests come back as 401 Unauthorized

• Resolution:
• Confirm the Authorization header is formatted correctly
• Check whether the API key has been disabled
• Confirm the key has not been deleted
• Check the key's validity period

Performance issues

Pages load slowly

• Suggestions:
• Enable OPCache
• Configure Redis caching
• Serve static assets from a CDN
• Optimize database queries

Database queries are slow

• Suggestions:
• Add appropriate indexes
• Purge stale data periodically
• Use a database connection pool
• Consider upgrading the hardware

Reading the logs

Log locations

• Application log: logs/app.log
• Access log: logs/access.log
• Error log: logs/error.log

Following logs live

# show the last 100 errors
tail -n 100 logs/error.log
```
## Getting support
If none of the above resolves it:
1. Capture the full error log
2. Write down the steps that reproduce it
3. Open an issue on GitHub to ask for help