appsmithorg/appsmith · critical · tlog

ERROR: Embedded MongoDB 7.0 failed to start on the existing

Q: What causes "ERROR: Embedded MongoDB 7.0 failed to start on the existing data. The most common cause is that the data is at featureCompatibilityVersion below the required 6.0 minimum." in appsmithorg/appsmith?

Stand up a temporary MongoDB 6.x container pointed at the same data files, run `db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })`, shut it down cleanly, then restart the Appsmith 2.x container.

Error message

ERROR: Embedded MongoDB 7.0 failed to start on the existing data. The most common cause is that the data is at featureCompatibilityVersion below the required 6.0 minimum.

What it means

Not a Java exception - this is a diagnostic message emitted by the Appsmith Docker entrypoint (entrypoint.sh) after the embedded MongoDB 7.0 pre-flight probe fails to start on the existing data directory. The script greps the probe log for featureCompatibilityVersion / upgrade / downgrade and prints a multi-line recovery block. Root cause: the on-disk MongoDB data is at FCV < 6.0, which MongoDB 7.x refuses to load. Affects only the embedded MongoDB; external-MongoDB deployments are not impacted. No Appsmith migrations have run yet, so rolling back to a 1.x image is safe.

Source

Thrown at deploy/docker/fs/opt/appsmith/entrypoint.sh:378

  # restarts. $TMP would be wiped, leaving no forensic trail when an admin comes
  # back to investigate why their container exited. Append rather than truncate so
  # repeated probe runs (e.g. multiple failed upgrade attempts) all stay on record.
  local probe_log="$MONGO_DB_PATH/fcv-probe.log"
  printf '\n===== Appsmith MongoDB FCV pre-flight probe @ %s =====\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$probe_log" 2>/dev/null || true
  if mongod --fork --port 27017 --dbpath "$MONGO_DB_PATH" --logpath "$probe_log" --logappend --bind_ip localhost >/dev/null 2>&1; then
    if ! mongod --dbpath "$MONGO_DB_PATH" --shutdown >/dev/null 2>&1; then
      tlog "ERROR: Pre-flight mongod probe started but shutdown failed. The probe mongod may still hold port 27017 or the data lock, which would prevent supervisord from starting mongod. Aborting. See $probe_log for details." >&2
      exit 1
    fi
    tlog "Pre-flight probe succeeded; mongodb-fixer will write the FCV marker after supervisord starts mongod"
    return
  fi

  local probe_err
  probe_err="$(grep -Ei 'featurecompatibilityversion|upgrade|downgrade' "$probe_log" 2>/dev/null | tail -n 1 || true)"
  tlog "====================================================================================================" >&2
  tlog "==" >&2
  tlog "== ERROR: Embedded MongoDB 7.0 failed to start on the existing data. The most common cause is that the data is at featureCompatibilityVersion below the required 6.0 minimum." >&2
  if [[ -n "$probe_err" ]]; then
    tlog "== mongod log: $probe_err" >&2
  fi
  tlog "==" >&2
  tlog "== About this error:" >&2
  tlog "==   Appsmith 2.x ships with MongoDB 7.x, which requires the database to be at featureCompatibilityVersion (FCV) 6.0 or higher. Appsmith releases 1.96 to 1.99 automatically raise FCV to 6.0 on boot, so any instance that has run one of those releases is fine. Instances that have only ever run Appsmith older than 1.70 may still be at FCV 5.0, which MongoDB 7.x refuses to load." >&2
  tlog "==" >&2
  tlog "==   This check only runs for instances using the embedded MongoDB. Instances configured with an external MongoDB are not affected." >&2
  tlog "==" >&2
  tlog "==   The failure happens during MongoDB pre-flight, before any Appsmith service comes online. No Appsmith database migrations have been attempted, so rolling back to a 1.x release is simply a matter of changing the image version on your deployment." >&2
  tlog "==" >&2
  tlog "== To recover:" >&2
  tlog "==" >&2
  tlog "==   1. Alter your Appsmith deployment to use a release in the 1.96 to 1.99 range (we recommend the latest, 1.99). These ship with MongoDB 6.x and will raise the compatibility version automatically." >&2
  tlog "==   2. Let the container start fully so the MongoDB FCV upgrade completes." >&2
  tlog "==   3. Shut down, then alter your Appsmith deployment to use this version again." >&2
  tlog "==" >&2
  tlog "== Full mongod log: $probe_log" >&2

View on GitHub (pinned to 8cd9021c24)

Solutions

Stand up a temporary MongoDB 6.x container pointed at the same data files, run `db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })`, shut it down cleanly, then restart the Appsmith 2.x container.
Alternatively roll the Appsmith image back to a 1.96-1.99 release (which boots MongoDB 6.x and auto-raises FCV), let it boot once, then upgrade to 2.x.
If the data is disposable, back up the volume, then start fresh (empty MongoDB data dir) - Appsmith will reinitialize.
Migrate to an external MongoDB at 6.0+ and configure Appsmith with MONGO_URI, bypassing the embedded check entirely.
Inspect the probe log referenced in the message (the path printed by tlog) for the exact mongod refusal line before choosing a path.

Example fix

# Before: container loop with the FCV error

# After: raise FCV with a throwaway mongo 6.x container, reusing the volume
docker run --rm -v appsmith_data:/data/db mongo:6 mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })'
# then restart appsmith
docker restart appsmith

Defensive patterns

Strategy: fallback

Validate before calling

#!/usr/bin/env bash
# Pre-upgrade FCV check - run BEFORE switching the Appsmith image to 2.x
MONGO_DATA=/var/lib/appsmith/data  # adjust to your volume mount
PROBE_IMG=mongo:6

docker run --rm -v "$MONGO_DATA":/data/db "$PROBE_IMG" \
  mongosh --quiet --eval 'db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 }).featureCompatibilityVersion.version' \
  | tr -d '"' | read fcv

if [[ -z "$fcv" ]]; then
  echo "Could not read FCV; aborting upgrade."; exit 1;
fi
if [[ "$fcv" < "6.0" ]]; then
  echo "FCV is $fcv (<6.0). Raising to 6.0 before upgrading Appsmith."
  docker run --rm -v "$MONGO_DATA":/data/db "$PROBE_IMG" \
    mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })'
else
  echo "FCV is $fcv; safe to upgrade."
fi

Prevention

Before any major Appsmith upgrade, snapshot the embedded-MongoDB volume.
Run an intermediate 1.96-1.99 release at least once to auto-raise FCV.
For production, prefer an external MongoDB 6.0+ to avoid embedded-FCV coupling entirely.
Always read the upgrade notes for the target Appsmith version - FCV requirements are documented.
Keep the probe log path from the error message handy for forensic reads.

When it happens

Trigger: Upgrading an Appsmith container (with a persistent embedded-MongoDB volume) from a pre-1.70 image directly to 2.x, skipping the 1.96-1.99 range that would have raised FCV to 6.0 automatically. The container fails to start, looping on this message.

Common situations: Long-running self-hosted instance that was pinned to an old Appsmith version then jumped to 2.x; a restored volume backup from an old FCV 5.0 era; an offline instance that never ran the intermediate releases.

Related errors

AI-assisted analysis of appsmithorg/appsmith@8cd9021c24 (2026-08-12). Data as JSON: /api/errors/aa059b0b9b1f4fec. Report an issue: GitHub.