Migration fails when upgrading to v25.12.1: `1050 Table 'imports' already exists`

[lennart-m]

Describe the Bug

I'm running BookStack in Docker using the linuxserver images.

After upgrading from v25.11.4 to v25.12.1 the app just shows:

I checked the logs and found:

   INFO  Running migrations.

  2024_11_02_160700_create_imports_table ......................... 1.99ms FAIL

   Illuminate\Database\QueryException

  SQLSTATE[42S01]: Base table or view already exists: 1050 Table 'imports' already exists (Connection: mysql, SQL: create table `imports` (`id` int unsigned not null auto_increment primary key, `name` varchar(191) not null, `path` varchar(191) not null, `size` int not null, `type` varchar(191) not null, `metadata` longtext not null, `created_by` int not null, `created_at` timestamp null, `updated_at` timestamp null) default character set utf8mb4 collate 'utf8mb4_unicode_ci')

  at /app/www/vendor/laravel/framework/src/Illuminate/Database/Connection.php:826
    822▕                     $this->getName(), $query, $this->prepareBindings($bindings), $e
    823▕                 );
    824▕             }
    825▕
  ➜ 826▕             throw new QueryException(
    827▕                 $this->getName(), $query, $this->prepareBindings($bindings), $e
    828▕             );
    829▕         }
    830▕     }

      +9 vendor frames

  10  /app/www/database/migrations/2024_11_02_160700_create_imports_table.php:14
      Illuminate\Support\Facades\Facade::__callStatic()
      +25 vendor frames

  36  /app/www/artisan:35
      Illuminate\Foundation\Console\Kernel::handle()

Running php artisan migrate produces the same error.

I have backups that contain the database dump so I can revert to the previous version.

Steps to Reproduce

Not sure if it's easy to reproduce. On another system that I use for testing the same upgrade worked like it should.

What I did was:

1. install bookstack with versions

   lscr.io/linuxserver/bookstack:v25.11.4-ls230
   lscr.io/linuxserver/mariadb:11.4.8-r0-ls200
   

2. upgrade to

   lscr.io/linuxserver/bookstack:v25.12.1-ls238
   lscr.io/linuxserver/mariadb:11.4.8-r0-ls201
   

Expected Behaviour

Migrations execute without error, app is usable after migrations.

Screenshots or Additional Context

Docker compose file:

# https://codeberg.org/bookstack/devops/src/branch/main/config/lsio-docker/docker-compose.yml#

services:
  # The container for BookStack itself
  bookstack:
    # You should update the version here to match the latest
    # release of BookStack: https://github.com/BookStackApp/BookStack/releases
    # You'll change this when wanting to update the version of BookStack used.
    image: lscr.io/linuxserver/bookstack:v25.12.1-ls238
    container_name: "bookstack-app"
    restart: unless-stopped
    environment:
      - APP_URL=https://bookstack...
      - APP_KEY=...
      - TZ=Europe/Berlin
      # db
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_DATABASE=bookstackapp
      - DB_USERNAME=bookstack
      - DB_PASSWORD=...
      # oauth
      - AUTH_METHOD=oidc
      - AUTH_AUTO_INITIATE=true
      - OIDC_NAME=Authelia
      - OIDC_DISPLAY_NAME_CLAIMS=name
      - OIDC_CLIENT_ID=bookstack
      - OIDC_CLIENT_SECRET=...
      - OIDC_ISSUER=https://auth...
      - OIDC_ISSUER_DISCOVER=true
      # oauth groups
      - OIDC_USER_TO_GROUPS=true
      - OIDC_GROUPS_CLAIM=groups
      - OIDC_ADDITIONAL_SCOPES=groups
      - OIDC_REMOVE_FROM_GROUPS=true
    volumes:
      - "/root/apps/bookstack/data:/config"
    depends_on:
      - bookstack_db
    networks:
      - internal
      - traefik
    labels:
      - traefik.enable=true
      - traefik.http.routers.bookstack.rule=Host(`bookstack...`)
      - traefik.http.services.bookstack.loadbalancer.server.port=80
      - traefik.docker.network=traefik

  bookstack_db:
    # You should update the version here to match the latest
    # main version of the linuxserver mariadb container version:
    # https://github.com/linuxserver/docker-mariadb/pkgs/container/mariadb/versions?filters%5Bversion_type%5D=tagged
    image: lscr.io/linuxserver/mariadb:11.4.8-r0-ls201
    container_name: "bookstack-db"
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=...
      - TZ=Europe/Berlin
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=...
    volumes:
      - "db-data:/config"
      - "/root/apps/bookstack/db-import:/import-data"
    networks:
      - internal

volumes:
  db-data:

networks:
  internal:
    driver: bridge
  traefik:
    external: true

Browser Details

No response

Exact BookStack Version

v25.12.1

[ssddanbrown]

Hi @lennart-m,

That error log during migration indicates a prior error/issue when attempting that command before (which runs at container start for that image). The database state of your instance is quite outdated relative to even v25.11.4.

This would be the general approach I'd advise:

• Stop the app/bookstack container.
• Backup all data for these containers. Ideally ensure you have a database dump in addition to backing up the volume files.
  • If needed I have a video on performing some common operations like these.
• Manually drop the imports table in the database, via the database container.
  • Usually done via a docker command or via entering a mysql shell for that database container.
  • Let me know if you need more detailed guidance on this.
• Start up the container stack, watching the logs for the app/bookstack container, noting any errors that appear on first start-up after making database changes.
  • Hopefully it will start without error, and run the existing pending database migrations.

Note: If you are using something like watchtower to auto-upgrade containers, I'd advise against that for BookStack where auto-upgrade timeouts can result in broken scenarios such as this.

[lennart-m]

Hi @ssddanbrown
Thanks a lot for the quick reply!
I deleted tables imports and sort_rules and then the server started 🥳📚

On start it said:

bookstack-db   | [migrations] started
bookstack-db   | [migrations] no migrations found

Does that mean everything is fine now?

Regarding the source of this issue, it was probably my fault. Some time ago my server crashed and I installed the newest version of bookstack (newest at that time; some months ago). I then restored my backup which was done using an older version of Bookstack.
The way I understand the migrations work is that the migration execution logs are stored in the DB; so the migrations for the new version were run on install, but the logs were deleted by my restored backup so the app tried to re-apply them (there were no logs for them) -- which failed. Is that plausible?
It's a bit strange that it was not a problem until I updated to the newest version a few days ago but I'm happy it works now. Maybe it is because only new tables failed as the restore did not delete them; it only deletes tables that existed when the backup was made (drop table if exists).

Regarding the updates, I don't use watchtower but since that mentioned crash I manage everything using ansible with fixed version tags for the docker images. So the next time I have to restore a backup, I will install the exact same image version because it's in my ansible role, and restore the backup in those. I will add a reminder to my playbook anyway.

[ssddanbrown]

Good to hear it's starting!

Does that mean everything is fine now?

I would check the start-up logs for the app container (bookstack service instead of bookstack-db) and make sure there are no errors there. It should hopefully mention something similar about not having any migrations to run.
What you have shared appear to be logs for the database container, which are not the migrations I'm worried about.

Is that plausible?

Yeah, that can lead to this. If restoring, it's important to restore into an empty database instead of one that's been set-up/created with a more recent version of BookStack, otherwise it can result in errors like the one you had.

[lennart-m]

The app container says:

bookstack-app  | Waiting for DB to be available
bookstack-app  |
bookstack-app  |    INFO  Nothing to migrate.
bookstack-app  |
bookstack-app  | [custom-init] No custom files found, skipping...
bookstack-app  | [ls.io-init] done.

So that looks fine.

Thanks for your support! 😊