sqlalchemy/alembic · error · TypeError

missing required positional argument: %s

Error message

missing required positional argument: %s

What it means

Raised as TypeError inside the translate() closure of ModuleClsProxy._create_method_proxy (langhelpers.py:178) during legacy-argument translation. When a method decorated with @_with_legacy_names is called positionally and a positional slot that maps to a renamed (now keyword) parameter is not supplied, translation runs out of args and reports the missing parameter name. It is effectively a richer TypeError for proxied methods with legacy aliases.

Source

Thrown at alembic/util/langhelpers.py:178

                    if oldname in kw:
                        warnings.warn(
                            "Argument %r is now named %r "
                            "for method %s()." % (oldname, newname, fn_name)
                        )
                        return_kw[newname] = kw.pop(oldname)
                return_kw.update(kw)

                args = list(args)
                if spec[3]:
                    pos_only = spec[0][: -len(spec[3])]
                else:
                    pos_only = spec[0]
                for arg in pos_only:
                    if arg not in return_kw:
                        try:
                            return_args.append(args.pop(0))
                        except IndexError:
                            raise TypeError(
                                "missing required positional argument: %s"
                                % arg
                            )
                return_args.extend(args)

                return return_args, return_kw

            globals_["_translate"] = translate
        else:
            outer_args = "*args, **kw"
            inner_args = "*args, **kw"
            translate_str = ""

        func_text = textwrap.dedent(
            """\
        def %(name)s(%(args)s):
            %(doc)r
            %(translate)s

View on GitHub (pinned to 44fb345033)

Solutions

1. Check the method signature in the current Alembic docs/version and supply the missing positional or use the new keyword name.
2. Update calls that use deprecated argument names (the DeprecationWarning tells you the new name).
3. Pin or align your Alembic version with the one the migrations were written for, then migrate the calls.
4. Pass arguments by keyword to be resilient to positional-order changes.

Example fix

# before (legacy positional, missing arg)
from alembic import op
op.alter_column('t', 'c', nullable=False)  # missing required renamed arg
# after: pass by keyword per current signature
op.alter_column('t', 'c', nullable=False, existing_type=sa.String())

import inspect
from alembic import op

def check_signature_compatible(meth_name: str, *args, **kwargs):
    meth = getattr(op, meth_name)
    sig = inspect.signature(meth)
    bound = sig.bind_partial(*args, **kwargs)
    bound.apply_defaults()
    missing = [p for n, p in sig.parameters.items()
               if p.default is inspect.Parameter.empty
               and p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
               and n not in bound.arguments]
    if missing:
        raise TypeError(f'{meth_name} missing required args: {missing}')

try:
    op.alter_column('t', 'c', existing_type=sa.String())
except TypeError as e:
    if 'missing required positional argument' in str(e):
        # consult current signature and supply the missing kwarg
        raise
    raise

When it happens

Trigger: Calling an op.* or Operations method that has _legacy_translations with too few positional arguments, relying on a renamed parameter that the caller omitted. The legacy translation machinery tries to map old positional order to new parameter order and finds a gap.

Common situations: Upgrading Alembic and an old code path still calls a method by its pre-rename positional signature; copy-pasted migration snippets from older tutorials that omit a now-required positional argument; calling op methods with keyword names that were renamed (triggers a DeprecationWarning) and simultaneously missing a positional arg.

Related errors

• constraint cannot be produced; original constraint is not pr
• operation is not reversible; original column is not present
• Can't invoke function '%s', as the proxy object has not yet
• The %s method does not apply to a batch table alter operatio
• Can't create table in batch mode

AI-assisted analysis of sqlalchemy/alembic@44fb345033 (2026-08-04). Data as JSON: /data/errors/8dd956d7b069356c.json. Report an issue: GitHub.