diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 0000000..bc3dc57
--- /dev/null
+++ b/Troubleshooting.md
@@ -0,0 +1,186 @@
+# Troubleshooting
+
+## Firebird mode still starts MSSQL initialization
+
+Check:
+
+```bash
+docker exec -it romexis-server env | grep -E 'SERVER_DB|ROMEXIS_DB|FIREBIRD'
+```
+
+Expected Firebird values:
+
+```text
+SERVER_DB=4
+ROMEXIS_DB_URL=jdbc:firebirdsql://firebird:3050//firebird/data/romexis.fdb
+ROMEXIS_DB_USER=sysdba
+ROMEXIS_DB_PASSWORD=pwr0mex!
+```
+
+If `SERVER_DB` is missing, the entrypoint may default to MSSQL:
+
+```bash
+SERVER_DB="${SERVER_DB:-5}"
+```
+
+Set:
+
+```env
+SERVER_DB=4
+```
+
+---
+
+## MSSQL_SA_PASSWORD required in Firebird mode
+
+This means the old MSSQL init script is still being executed or old script content is present in the image.
+
+Check inside the Romexis container:
+
+```bash
+cat /opt/init-romexis-db.sh
+ls -lah /opt/init-romexis-*
+```
+
+The wrapper must not contain:
+
+```bash
+MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:?MSSQL_SA_PASSWORD is required}"
+```
+
+That belongs only in:
+
+```text
+/opt/init-romexis-mssql-db.sh
+```
+
+Rebuild without cache:
+
+```bash
+docker buildx prune -a -f
+docker compose build --no-cache --pull
+docker compose up --force-recreate
+```
+
+---
+
+## Firebird shows unixODBC isql help
+
+If you see:
+
+```text
+unixODBC - isql and iusql
+```
+
+then the wrong `isql` tool is used.
+
+Use:
+
+```bash
+isql-fb
+```
+
+Set:
+
+```bash
+export ISQL=isql-fb
+```
+
+Or change the init script default:
+
+```bash
+ISQL="${ISQL:-isql-fb}"
+```
+
+---
+
+## Firebird database file already exists
+
+If the Firebird container creates the database using:
+
+```yaml
+FIREBIRD_DATABASE: "romexis.fdb"
+```
+
+then the Romexis init script should not run `CREATE DATABASE` again.
+
+It should connect to the existing empty database and import the SQL scripts.
+
+---
+
+## Firebird SYSDBA duplicate key error
+
+Error:
+
+```text
+violation of PRIMARY or UNIQUE KEY constraint
+PLG$USER_NAME = 'SYSDBA'
+```
+
+Cause:
+
+The Firebird container was instructed to create `SYSDBA` again.
+
+Remove user creation variables from the Firebird service and keep only:
+
+```yaml
+environment:
+  ISC_PASSWORD: "${FIREBIRD_PASSWORD}"
+  FIREBIRD_DATABASE: "romexis.fdb"
+```
+
+---
+
+## Payload latest tag not found
+
+Error:
+
+```text
+romexis-firebird-payload:latest: not found
+```
+
+Fix the Firebird payload CI build to push:
+
+```bash
+-t "$FIREBIRD_PAYLOAD_IMAGE:latest"
+```
+
+---
+
+## Build still uses old files
+
+Clean local build cache:
+
+```bash
+docker buildx prune -a -f
+```
+
+Then rebuild with:
+
+```bash
+docker compose build --no-cache --pull
+```
+
+In CI, also check whether the build is skipped because the image already exists in the registry.
+
+---
+
+## Start container with bash for debugging
+
+In Compose:
+
+```yaml
+entrypoint:
+  - /bin/bash
+  - -c
+  - sleep infinity
+
+stdin_open: true
+tty: true
+```
+
+Then:
+
+```bash
+docker compose exec romexis bash
+```