Flask-MongoEngine

Common errors

• pymongo.errors.ConfigurationError: The 'PyMongo' package requires PyMongo >=3.6.0.

  cause You are using Flask-MongoEngine v1.0.0 or newer, but your PyMongo installation is older than version 3.6.0, which is no longer supported.
  fix Upgrade PyMongo to a compatible version: `pip install --upgrade pymongo`.

• SyntaxError: invalid syntax

  cause This error, particularly on `f"..."` strings or `async`/`await` keywords, indicates you're running Flask-MongoEngine v1.0.0+ on an unsupported Python version (e.g., Python 2.x or <3.6).
  fix Upgrade your Python environment to 3.6 or newer. If upgrading Python is not feasible, downgrade Flask-MongoEngine to a compatible version (e.g., `pip install "flask-mongoengine<1.0.0"`).

• mongoengine.errors.NotRegistered: Document type 'MyDocument' not registered.

  cause This typically means the MongoEngine instance was not correctly initialized with the Flask app, or the Document class was not defined before `db = MongoEngine(app)` was called, or an incompatible MongoEngine version is installed.
  fix Ensure `db = MongoEngine(app)` is called after defining `app` and its configuration. Verify your `mongoengine` package version is compatible with your `flask-mongoengine` version (e.g., `mongoengine>=0.15.0` for `flask-mongoengine>=1.0.0`).

• pymongo.errors.ConnectionFailure: [Errno 111] Connection refused

  cause The Flask application could not establish a connection to the MongoDB server. This usually means the server is not running or the `MONGODB_HOST` configuration is incorrect.
  fix Ensure your MongoDB server is running and accessible. Double-check the `MONGODB_HOST` configuration string in your Flask app to ensure it points to the correct address and port (e.g., `mongodb://localhost:27017/mydb`).

Warnings

• breaking Flask-MongoEngine v1.0.0 dropped support for Python versions 2.7 through 3.5. Applications using these Python versions will fail to install or run.
  Fix: Upgrade your Python environment to 3.6 or newer. If upgrading Python is not an option, you must use Flask-MongoEngine <1.0.0 (e.g., `pip install "flask-mongoengine<1.0.0"`).
• breaking Flask-MongoEngine v1.0.0 dropped support for PyMongo versions older than 3.6.0. An incompatible PyMongo version will lead to configuration errors.
  Fix: Ensure PyMongo is updated to version 3.6.0 or newer: `pip install --upgrade pymongo`.
• breaking Flask-MongoEngine v0.8 dropped support for MongoEngine 0.7. Using an older MongoEngine version will lead to various compatibility issues and errors.
  Fix: Ensure MongoEngine is updated to a compatible version (0.10+ for v0.8, and 0.15+ for v1.0.0): `pip install --upgrade mongoengine`.
• deprecated MongoEngine's `help_text` and `safe` attributes for fields were deprecated prior to Flask-MongoEngine v0.7.5. While Flask-MongoEngine handles some of these changes, direct usage in custom forms might still lead to warnings or errors in newer MongoEngine versions.
  Fix: Update MongoEngine and Flask-MongoEngine to their latest versions. Replace `help_text` with `description` in `StringField`, `IntField` etc. if directly passing them to `mongoengine.fields`.

Install

• pip install flask-mongoengine Install latest version

Imports

• MongoEngine

  from flask_mongoengine import MongoEngine

• Document

  from mongoengine import Document, StringField, IntField

  MongoEngine's Document class is used directly, not through flask_mongoengine

Quickstart

This quickstart sets up a basic Flask application with Flask-MongoEngine, connects to a local MongoDB instance (or one specified by MONGODB_URI), defines a simple 'User' document, and demonstrates creating and retrieving users via a Flask route.

import os
from flask import Flask
from flask_mongoengine import MongoEngine
from mongoengine import Document, StringField, IntField

app = Flask(__name__)

# Configure MongoDB connection
# Use an environment variable for production readiness
app.config["MONGODB_HOST"] = os.environ.get("MONGODB_URI", "mongodb://localhost/testdb")

db = MongoEngine(app)

class User(Document):
    name = StringField(required=True)
    age = IntField()
    meta = {'collection': 'users'}

@app.route('/')
def index():
    # Ensure collection is empty for repeatable test runs
    User.drop_collection()

    # Create a user
    user = User(name="Alice", age=30)
    user.save()

    # Create another user
    User(name="Bob", age=25).save()

    # Find users
    all_users = User.objects.all()
    names = [u.name for u in all_users]

    return f"<h1>Users in MongoDB:</h1><p>{', '.join(names)}</p>"