sqlalchemy/alembic · error · Exception

Connection, url, or dialect_name is required.

Error message

Connection, url, or dialect_name is required.

What it means

Raised as a bare Exception by MigrationContext.configure() (migration.py:248-269) when none of connection, url, or dialect_name was supplied and no dialect could be derived otherwise. The factory builds a dialect from one of those sources (connection.dialect, url.get_dialect(), or makeURL('name://')); if all are absent it cannot proceed.

Solutions

1. Pass one of connection=, url=, or dialect_name= to MigrationContext.configure() (or to EnvironmentContext.configure which forwards it).
2. In env.py offline branch, supply url=config.get_main_option("sqlalchemy.url").
3. Ensure alembic.ini has a non-empty sqlalchemy.url (or that the URL is injected via env).

Example fix

// before (offline)
context.configure(url=None, target_metadata=target_metadata)
// after
context.configure(
    url=config.get_main_option("sqlalchemy.url"),
    target_metadata=target_metadata,
)

# Verify a dialect source is available before configure().
def ensure_dialect_source(connection=None, url=None, dialect_name=None):
    if not any([connection, url, dialect_name]):
        raise ValueError(
            'MigrationContext.configure requires one of connection, url, or dialect_name'
        )

url = config.get_main_option('sqlalchemy.url')
ensure_dialect_source(url=url)
context.configure(url=url, target_metadata=target_metadata)

def has_dialect_source(connection=None, url=None, dialect_name=None) -> bool:
    return any([connection, url, dialect_name])

When it happens

Trigger: Calling MigrationContext.configure() with no connection/url/dialect_name; an env.py that, in offline mode, forgets to pass url=config.get_main_option('sqlalchemy.url'); a programmatic caller that constructs MigrationContext directly without specifying how to reach the DB.

Common situations: Misconfigured alembic.ini with a blank sqlalchemy.url; offline (offline=True) migrations where the url option is missing; custom command scripts that call configure() with only opts=.

Related errors

• No context has been configured yet.
• A plugin named is already registered
• Can't drop table in batch mode
• constraint cannot be produced; original constraint is not…
• Constraint must have a name

AI-assisted analysis of sqlalchemy/alembic@5551b5d35f (2026-08-11). Data as JSON: /api/errors/7964e79cc8ea4974. Report an issue: GitHub.

Appendix: source

Thrown at alembic/runtime/migration.py:269

            dialect_opts = {}

        if connection:
            if isinstance(connection, Engine):
                raise util.CommandError(
                    "'connection' argument to configure() is expected "
                    "to be a sqlalchemy.engine.Connection instance, "
                    "got %r" % connection,
                )

            dialect = connection.dialect
        elif url:
            url_obj = sqla_url.make_url(url)
            dialect = url_obj.get_dialect()(**dialect_opts)
        elif dialect_name:
            url_obj = sqla_url.make_url("%s://" % dialect_name)
            dialect = url_obj.get_dialect()(**dialect_opts)
        elif not dialect:
            raise Exception("Connection, url, or dialect_name is required.")
        assert dialect is not None
        return MigrationContext(dialect, connection, opts, environment_context)

    @contextmanager
    def autocommit_block(self) -> Iterator[None]:
        """Enter an "autocommit" block, for databases that support AUTOCOMMIT
        isolation levels.

        This special directive is intended to support the occasional database
        DDL or system operation that specifically has to be run outside of
        any kind of transaction block.   The PostgreSQL database platform
        is the most common target for this style of operation, as many
        of its DDL operations must be run outside of transaction blocks, even
        though the database overall supports transactional DDL.

        The method is used as a context manager within a migration script, by
        calling on :meth:`.Operations.get_context` to retrieve the
        :class:`.MigrationContext`, then invoking

View on GitHub (pinned to 5551b5d35f)