Troubleshooting

Troubleshooting

Solutions to common issues when running BookStorage.

---

Table of contents

• SECRET_KEY must be at least 32 bytes
• bsctl: command not found
• Readonly database error
• Port already in use
• Permission denied during PostgreSQL migration
• View detailed logs

---

SECRET_KEY must be at least 32 bytes

Error:

BOOKSTORAGE_SECRET_KEY must be at least 32 bytes when BOOKSTORAGE_ENV=production

Cause: In production mode, the session secret key must be a non-default string of at least 32 characters.

Fix:

1. Generate a strong key:

openssl rand -base64 48

2. Set it in /opt/bookstorage/.env:

BOOKSTORAGE_SECRET_KEY=your-generated-key-here

3. Secure the file and restart:

chmod 600 /opt/bookstorage/.env
systemctl restart bookstorage

Do not shorten the key or use a simple string. Use a password manager or the openssl command above.

---

bsctl: command not found

Error:

sudo: bsctl: command not found

Cause: bsctl is installed under /usr/local/bin. Some sudo configurations use a restricted PATH (secure_path in /etc/sudoers) that omits /usr/local/bin.

Fix: Use the full path:

sudo /usr/local/bin/bsctl install
sudo /usr/local/bin/bsctl update main

If you are already logged in as root, run bsctl without sudo (your shell already has the correct PATH).

---

Readonly database error

Error:

attempt to write a readonly database

Fix:

bsctl fix-perms
bsctl restart

This corrects file ownership and permissions on the SQLite database and related directories.

---

Port already in use

Error:

listen tcp :5000: bind: address already in use

Fix:

1. Find the process using the port:

sudo lsof -i :5000

2. Either stop the conflicting process or change the BookStorage port in .env:

BOOKSTORAGE_PORT=5001

3. Restart:

bsctl restart

---

Permission denied during PostgreSQL migration

Error: The SQLite to PostgreSQL migration wizard fails with permission denied when trying to write BOOKSTORAGE_POSTGRES_URL to the .env file.

Cause: The process user from bookstorage.service (default: nobody) cannot write to /opt/bookstorage/.env. This happens when .env was created as root:root with mode 600.

Fix:

sudo chown nobody /opt/bookstorage/.env
sudo chmod 600 /opt/bookstorage/.env
sudo systemctl restart bookstorage

Replace nobody with whatever user is configured in the User= directive of your systemd unit file. Then re-run Admin > PostgreSQL > Migrate.

New installs from deploy/install.sh set .env ownership to the service user automatically.

---

View detailed logs

To see real-time application logs:

bsctl logs

This runs journalctl -u bookstorage -f under the hood.

For backup logs:

journalctl -u bookstorage-backup.service

For Prometheus logs:

journalctl -u bookstorage-prometheus

---

Home — Back to the wiki home page.