{"record":{"id":"aa059b0b9b1f4fec","repo":"appsmithorg/appsmith","slug":"error-embedded-mongodb-7-0-failed-to-start-on-the","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"console","errorClass":"tlog","httpStatus":null,"severity":"critical","filePath":"deploy/docker/fs/opt/appsmith/entrypoint.sh","lineNumber":378,"sourceCode":"  # restarts. $TMP would be wiped, leaving no forensic trail when an admin comes\n  # back to investigate why their container exited. Append rather than truncate so\n  # repeated probe runs (e.g. multiple failed upgrade attempts) all stay on record.\n  local probe_log=\"$MONGO_DB_PATH/fcv-probe.log\"\n  printf '\\n===== Appsmith MongoDB FCV pre-flight probe @ %s =====\\n' \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" >> \"$probe_log\" 2>/dev/null || true\n  if mongod --fork --port 27017 --dbpath \"$MONGO_DB_PATH\" --logpath \"$probe_log\" --logappend --bind_ip localhost >/dev/null 2>&1; then\n    if ! mongod --dbpath \"$MONGO_DB_PATH\" --shutdown >/dev/null 2>&1; then\n      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\n      exit 1\n    fi\n    tlog \"Pre-flight probe succeeded; mongodb-fixer will write the FCV marker after supervisord starts mongod\"\n    return\n  fi\n\n  local probe_err\n  probe_err=\"$(grep -Ei 'featurecompatibilityversion|upgrade|downgrade' \"$probe_log\" 2>/dev/null | tail -n 1 || true)\"\n  tlog \"====================================================================================================\" >&2\n  tlog \"==\" >&2\n  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\n  if [[ -n \"$probe_err\" ]]; then\n    tlog \"== mongod log: $probe_err\" >&2\n  fi\n  tlog \"==\" >&2\n  tlog \"== About this error:\" >&2\n  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\n  tlog \"==\" >&2\n  tlog \"==   This check only runs for instances using the embedded MongoDB. Instances configured with an external MongoDB are not affected.\" >&2\n  tlog \"==\" >&2\n  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\n  tlog \"==\" >&2\n  tlog \"== To recover:\" >&2\n  tlog \"==\" >&2\n  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\n  tlog \"==   2. Let the container start fully so the MongoDB FCV upgrade completes.\" >&2\n  tlog \"==   3. Shut down, then alter your Appsmith deployment to use this version again.\" >&2\n  tlog \"==\" >&2\n  tlog \"== Full mongod log: $probe_log\" >&2","sourceCodeStart":360,"sourceCodeEnd":396,"githubUrl":"https://github.com/appsmithorg/appsmith/blob/8cd9021c24cdbea1c3c12c966073708e83db60c2/deploy/docker/fs/opt/appsmith/entrypoint.sh#L360-L396","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# Before: container loop with the FCV error\n\n# After: raise FCV with a throwaway mongo 6.x container, reusing the volume\ndocker run --rm -v appsmith_data:/data/db mongo:6 mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: \"6.0\" })'\n# then restart appsmith\ndocker restart appsmith","handlingStrategy":"fallback","validationCode":"#!/usr/bin/env bash\n# Pre-upgrade FCV check - run BEFORE switching the Appsmith image to 2.x\nMONGO_DATA=/var/lib/appsmith/data  # adjust to your volume mount\nPROBE_IMG=mongo:6\n\ndocker run --rm -v \"$MONGO_DATA\":/data/db \"$PROBE_IMG\" \\\n  mongosh --quiet --eval 'db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 }).featureCompatibilityVersion.version' \\\n  | tr -d '\"' | read fcv\n\nif [[ -z \"$fcv\" ]]; then\n  echo \"Could not read FCV; aborting upgrade.\"; exit 1;\nfi\nif [[ \"$fcv\" < \"6.0\" ]]; then\n  echo \"FCV is $fcv (<6.0). Raising to 6.0 before upgrading Appsmith.\"\n  docker run --rm -v \"$MONGO_DATA\":/data/db \"$PROBE_IMG\" \\\n    mongosh --eval 'db.adminCommand({ setFeatureCompatibilityVersion: \"6.0\" })'\nelse\n  echo \"FCV is $fcv; safe to upgrade.\"\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["appsmith","mongodb","docker","upgrade","feature-compatibility-version","embedded-mongodb","entrypoint"],"backgroundTag":null,"analyzedSha":"8cd9021c24cdbea1c3c12c966073708e83db60c2","analyzedAt":"2026-08-12T22:14:19.293Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}