[BUG] grocy 4.7.0 (ls338) silently breaks existing installs — undocumented breaking change to AUTH_CLASS

Start with readme-vars.yml and review nearby entries for the existing-user warning format. Add a changelog notice covering the AUTH_CLASS migration described in the issue, then verify the entry matches the repository’s prior breaking-change notices; the optional Dockerfile bump-flow improvement is separate.

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

Updating to v4.7.0-ls338 (grocy 4.7.0, built 2026-08-28) breaks every existing install whose config.php has not been manually migrated.

The container starts cleanly and stays running, but every HTTP request returns:

Invalid setting in config.php: Configured AUTH_CLASS "Grocy\Middleware\DefaultAuthMiddleware" does not exist

----------
Check your "config.php" file (which is in your data directory: "/config/data").
Defaults can be found in "config-dist.php" (which is in your main Grocy directory: "/app/www").

Two things make this unusually hard to notice:

• The error page is served with HTTP 200, not a 5xx, so uptime and health checks do not flag it.
• Nothing appears in the container logs. The log ends with [ls.io-init] done. and no error, because grocy evaluates config.php per request rather than at startup.

Upstream reorganized the auth middleware in 4.7.0 and flagged it in the release notes:

⚠️ Authentication middleware was reorganized, review your AUTH_CLASS setting (see the default reference in config-dist.php as usual)

https://github.com/grocy/grocy/releases/tag/v4.7.0

The namespace moved from Grocy\Middleware to Grocy\Middleware\Auth:

v4.6.0   middleware/DefaultAuthMiddleware.php        namespace Grocy\Middleware
v4.7.0   middleware/Auth/DefaultAuthMiddleware.php   namespace Grocy\Middleware\Auth

There is no class_alias or other back-compat shim upstream, so this is a hard break for every pre-4.7.0 config.php.

Why it reaches users with no warning

The grocy version is not pinned — the Dockerfile resolves it at build time:

if [ -z ${GROCY_RELEASE+x} ]; then \
  GROCY_RELEASE=$(curl -sX GET "https://api.github.com/repos/grocy/grocy/releases/latest" \
  | jq -r '.tag_name'); \
fi

So the scheduled rebuild picked up v4.7.0 within hours of upstream publishing it, and the only resulting commit was Bot Updating Package Versions (c5b27c49, 2026-08-28), touching package_versions.txt alone. There is no point in that flow where upstream's release notes are seen, so a documented upstream breaking change reaches every auto-updating user with no notice.

Expected Behavior

A changelog entry in readme-vars.yml warning that existing users must update AUTH_CLASS, consistent with how previous breaking changes have been handled in this repo:

• 06.03.24: Existing users should update: site-confs/default.conf - Cleanup default site conf.
• 30.06.24: Rebase to Alpine 3.20. Existing users should update their nginx confs to avoid http2 deprecation warnings.

Optionally, surfacing upstream release notes somewhere in the bump flow would let breaking changes like this be caught before publish.

Steps To Reproduce

1. Run any grocy image up to and including 4.6.0, with an existing config.php in /config/data that sets AUTH_CLASS to the pre-4.7.0 default.
2. Update the container to the current image (v4.7.0-ls338).
3. Load the web UI.
4. The error above is returned instead of the login page, with HTTP 200 and a clean container log.

Environment

- OS: Unraid 7.3.2
- How docker service was installed: bundled with Unraid

CPU architecture

x86-64

Docker creation

docker run -d \
  --name='grocy' \
  --net='bridge' \
  -e PUID=99 \
  -e PGID=100 \
  -p '9283:80/tcp' \
  -v '/mnt/user/appdata/grocy':'/config':'rw' \
  'lscr.io/linuxserver/grocy'

Container logs

[migrations] started
[migrations] 01-nginx-site-confs-default: skipped
[migrations] 02-default-location: skipped
[migrations] done
───────────────────────────────────────
      ██╗     ███████╗██╗ ██████╗
      ██║     ██╔════╝██║██╔═══██╗
      ██║     ███████╗██║██║   ██║
      ██║     ╚════██║██║██║   ██║
      ███████╗███████║██║╚██████╔╝
      ╚══════╝╚══════╝╚═╝ ╚═════╝

   Brought to you by linuxserver.io
───────────────────────────────────────

To support LSIO projects visit:
https://www.linuxserver.io/donate/
───────────────────────────────────────
GID/UID
───────────────────────────────────────

User UID:    99
User GID:    100
───────────────────────────────────────
Linuxserver.io version: v4.7.0-ls338
Build-date: 2026-08-28T18:40:32+00:00
───────────────────────────────────────

using keys found in /config/keys
[custom-init] No custom files found, skipping...
[ls.io-init] done.

Note: the log above is from the container after applying the workaround below. The startup output was identical while broken — grocy only evaluates config.php per request, so there is no log signal in either state. That absence of any error in the logs is the main reason this took a while to track down.

Workaround

For anyone else hitting this, either update the AUTH_CLASS line in /config/data/config.php:

Setting('AUTH_CLASS', 'Grocy\Middleware\Auth\DefaultAuthMiddleware');

or set it as an environment variable, which grocy honours ahead of config.php:

GROCY_AUTH_CLASS=Grocy\Middleware\Auth\DefaultAuthMiddleware

The environment variable route works in this image thanks to the clear_env = no change in #85.