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.py is 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.sql is present in the root directory.
Action: Delete the existing database.db (if it is empty/corrupted) and run python3 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_seconds value in config.json.
Check: Ensure the application has write permissions for the flask_session directory. If the server cannot write session files, it cannot maintain user state.
Action: In config.json, ensure session_storage_dir points 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_KEY in your .env or config.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.json contains a valid flask_secret_key under the secrets object.
Dependency Issues: Run pip install -r requirements.txt to ensure all libraries, particularly Flask-Session and bcrypt, 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 of main.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 user table in database.db is 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/list or /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.json has correctly defined string_length_limits. If data being sent to the API exceeds these limits (e.g., a username longer than 64 characters), the API will return a 400 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 DB class in db_engine.py has a log_level. Setting this to 2 will print every database transaction to the console.
Flask Debug Mode: Ensure debug=True is set in app.run() (default in development) to see interactive tracebacks in the browser.
Session Files: You can manually inspect the ./flask_session folder to see if session files are being generated when a user logs in.