April 14, 2026
users.json is not an array
Login failed with TypeError: users.find is not a function. The file was {} instead of [], and the seeder that should have saved me silently skipped because users.length === 0 is false when users is an object.
The login failed with a 401 and dumped a stack trace into the console that had the answer in it.

Authentication error: TypeError: users.find is not a function
at findUserByUsername (file:///app/server/auth.js:55:16)
at validatePassword (file:///app/server/auth.js:93:16)
at authenticate (file:///app/server/auth.js:252:24)
users.find throws when users isn't an array, and that's what was happening here.
What the file actually held
I shelled into the demo backend on VM 121 and read the file that loadUsers() reads. It parsed fine as JSON, but the shape was wrong.
$ docker exec homelabarr-demo-backend cat /app/server/config/users.json
{}
An empty object, where the code expected an array. Every call that walked the user list (users.find, users.filter, users.push) blew up the moment it ran.
I checked the prod backend on the same VM and found the same {} on disk in both files.
The part that didn't save me
HomelabARR CE has a seeder. On startup the backend calls initializeAuth(), which does this:
const users = loadUsers();
if (users.length === 0) {
// ... create default admin from DEFAULT_ADMIN_PASSWORD
}
That looks like it should have rescued me. A malformed users.json, no valid admin on disk, the seeder fires, default credentials get recreated, life goes on.
It did not rescue me.
users was {}. {}.length is undefined. undefined === 0 is false. So the seeder decided there were already users and did nothing. Nothing logged it, no error or warning anywhere, so the backend booted clean and then blew up the first time anyone tried to sign in.
The check I thought was defensive did nothing on the wrong type. length === 0 only guards an array; hand it an object and the object sails straight through.
The fix
I reset both files to [], restarted the backends, and the seeder ran the way it was supposed to. Default admin got recreated from DEFAULT_ADMIN_PASSWORD (which defaults to admin), and login worked again.
Then I opened server/auth.js and added the guard that should have been there the whole time. Here is the real diff, from loadUsers():
// server/auth.js (before)
const data = fs.readFileSync(USERS_FILE, 'utf8');
return JSON.parse(data);
// server/auth.js (after)
const data = fs.readFileSync(USERS_FILE, 'utf8');
const parsed = JSON.parse(data);
// Guard against malformed state (e.g. users.json saved as {} instead of []).
// Without this, every downstream call (users.find, users.length) breaks and
// the default-admin seeder never runs because `users.length === 0` is false
// for non-arrays.
if (!Array.isArray(parsed)) {
console.warn(`users.json is not an array (got ${typeof parsed}) — ignoring and returning []. File will be rewritten on next save.`);
return [];
}
return parsed;
Four lines. It logs the bad value and returns an empty array so the seeder can do its job. (Commit 164a459 on CE, shipped in PR #165.)
Now a malformed users.json just produces a warning in the logs and a backend that still works. Before, it produced a 401 at the login modal and a stack trace nobody sees until they open the network tab.
Cherry-picked to Eight.ly
Eight.ly Container Edition is a fork of CE. The server/auth.js in the Eight.ly repo is byte-for-byte identical here. Same missing guard, same class of bug waiting to happen on any customer install if someone ever saves the wrong shape to that file.
I opened the Eight.ly repo, applied the same four lines, and pushed and merged a PR (commit b06e39b, PR #8). The commit message says it plainly: "CE and Eight.ly share this auth module. A malformed users.json (seen as {} in the wild on VM 121 earlier today) caused TypeError: users.find is not a function on every login attempt." Same guard now sits in both repos.
Where the empty object came from
My first question was how the file ended up as {} in the first place. Both backends had been running for eleven days before this. The containers were healthy. The demo was working, at least for whoever wasn't trying to log in.
My first theory: earlier in the day I did a template-mount cleanup on that VM, which involved stopping and recreating the backend containers. The volumes survived the recreate, so the users.json state predates the recreate. Which means this file was {} for some unknown span of time before today and nobody noticed, because the only thing that read it was the login path.
A demo runs in two states, browsed and logged-in. The demo had been browsable for eleven days. It stopped being logged-in-able some number of days before that, silently, and I only caught it because I tried to sign in after a container restart forced the seeder path.
The seeder-skips-on-non-arrays bug is fixed now. The question of what wrote the {} was a separate one.
It wasn't upstream, it was the startup script. CE's
start.shwas seeding the config files the wrong way. The commit that fixed it tells the whole story:# server/start.sh (before) for f in users.json api-keys.json stars.json; do [ ! -f "$CONFIG_DIR/$f" ] && echo '{}' > "$CONFIG_DIR/$f" && echo " Created $CONFIG_DIR/$f" done# server/start.sh (after) for f in users.json api-keys.json; do [ ! -f "$CONFIG_DIR/$f" ] && echo '[]' > "$CONFIG_DIR/$f" && echo " Created $CONFIG_DIR/$f" done [ ! -f "$CONFIG_DIR/stars.json" ] && echo '{}' > "$CONFIG_DIR/stars.json" && echo " Created $CONFIG_DIR/stars.json"
users.jsonandapi-keys.jsonare arrays,stars.jsonis an object, and the original loop stamped{}onto all three. The fix split them: arrays seeded as[],stars.jsonleft as{}. That commit (7d43f7b) landed on April 2, twelve days before the login broke, which lines up exactly with a fresh config dir on that VM getting seeded with the wrong shape. The loader guard above is still the right fix, because the loader should never trust the file no matter who wrote it, and in this case the thing that wrote{}was mine.