Troubleshooting
Common Issues and Solutions
This section covers common challenges encountered when setting up or operating the Atslegas system. As a Flask-based application utilizing SQLite, most issues are related to file permissions, session storage, or database locks.
Database Connection Errors
The system uses SQLite with Write-Ahead Logging (WAL) to handle concurrent access.
"Database is locked" (OperationalError)
This occurs when multiple processes attempt to write to the database.db file simultaneously beyond the 5-second timeout.
- Solution: Ensure no other database management tools (like DB Browser for SQLite) are holding an active transaction on the file.
- Action: If the error persists, restart the Flask server to clear any hung connections. The
db_engine.pyis configured to retry writes automatically, so a single occurrence is usually handled by the system.
Database Schema Not Found
If the application starts but encounters errors about missing tables (e.g., no such table: user).
- Solution: Ensure
schema.sqlis present in the root directory. - Action: Delete the existing
database.db(if it is empty/corrupted) and runpython3 main.py. The system will automatically re-initialize the database using the schema file.
Session and Authentication Issues
Atslegas uses server-side filesystem sessions stored in the directory defined in config.json.
Unexpected Logouts
If users are being logged out before the expected one-hour timeout.
- Check: Verify the
timeout_secondsvalue inconfig.json. - Check: Ensure the application has write permissions for the
flask_sessiondirectory. If the server cannot write session files, it cannot maintain user state. - Action: In
config.json, ensuresession_storage_dirpoints to a valid, writable path.
401 Unauthorized Errors in the Dashboard
The Admin Dashboard relies on a heartbeat check and session validation.
- Solution: If you receive a "session timed out" or "invalid session" JSON error while using the dashboard, clear your browser cookies and log in again.
- Developer Tip: During development, if you change the
FLASK_SECRET_KEYin your.envorconfig.json, all existing session files become invalid and users must re-authenticate.
Configuration and Environment
Application Fails to Start
If the server crashes immediately upon running python3 main.py.
- Missing Secret Key: Ensure
config.jsoncontains a validflask_secret_keyunder thesecretsobject. - Dependency Issues: Run
pip install -r requirements.txtto ensure all libraries, particularlyFlask-Sessionandbcrypt, are installed. - Port Conflict: By default, the app runs on port
5000. If another service is using this port (common on macOS), change the port in the last line ofmain.py:app.run(debug=True, port=5001)
Default Credentials Not Working
If you cannot log in with root / root on a fresh installation.
- Action: Check the server console output during the first run. It should log
Created default root user. - Action: If the user was not created, you can manually trigger the creation by ensuring the
usertable indatabase.dbis empty and restarting the app.
Frontend and API Connectivity
Dashboard Data Not Loading
If the admin interface appears but lists are empty or loading spinners persist.
- Check: Open the browser's Developer Tools (F12) and check the "Network" tab. Look for failed requests to
/api/key/listor/api/user/list. - Common Cause: This is often due to the session having expired while the frontend state remained active.
- Solution: Refresh the page. If the system redirects you to
/login, your session had expired.
Script Errors in admin-common.js
The admin panel aggregates data from multiple API endpoints.
- Check: Ensure
config.jsonhas correctly definedstring_length_limits. If data being sent to the API exceeds these limits (e.g., a username longer than 64 characters), the API will return a400 Bad Request, causing the frontend scripts to fail during data synchronization.
Logging and Debugging
To get more detailed information about what is happening under the hood:
- DB Logs: The
DBclass indb_engine.pyhas alog_level. Setting this to2will print every database transaction to the console. - Flask Debug Mode: Ensure
debug=Trueis set inapp.run()(default in development) to see interactive tracebacks in the browser. - Session Files: You can manually inspect the
./flask_sessionfolder to see if session files are being generated when a user logs in.