sqlalchemy/alembic · error · TypeError

missing required positional argument

Error message

missing required positional argument: %s

What it means

Raised as TypeError by the _translate helper inside _create_method_proxy when a method using legacy argument name translations is called with too few positional arguments to fill a required positional-only parameter (langhelpers.py:173-181). This occurs specifically for methods decorated with @_with_legacy_names where old argument names are being mapped to new ones, and the caller hasn't supplied enough positional values.

Solutions

1. Check the method signature in the current Alembic docs/API and supply all required positional arguments.
2. If using deprecated argument names (which trigger a DeprecationWarning), switch to the new names.
3. Provide arguments explicitly as keyword arguments matching the current parameter names.
4. Inspect the full traceback to identify which method and which argument is missing.

Example fix

# before (missing positional arg, using deprecated name)
op.alter_column('users', 'name', nullable=True, oldname='full_name')
# oldname is deprecated; missing table_name positional?

# after (all required positionals, current arg names)
op.alter_column('users', 'name', nullable=True, new_column_name='full_name')

import inspect

def has_required_args(fn, *args, **kwargs):
    sig = inspect.signature(fn)
    try:
        sig.bind(*args, **kwargs)
        return True
    except TypeError:
        return False

When it happens

Trigger: Calling an Alembic proxied method that has _legacy_translations defined, without passing enough positional arguments to cover all positional-only parameters. The translate function at langhelpers.py:168-181 pops from args for each pos_only param and raises TypeError on IndexError. This is an internal mechanism for backward-compatible argument renaming.

Common situations: Calling an Alembic API method with keyword arguments using old deprecated names while missing a required positional argument. Upgrading Alembic and hitting renamed parameters where the call site relied on positional ordering. Partial argument migration where some old names are used but positionals are incomplete.

Related errors

• Can't invoke function
• A plugin named is already registered
• Can not set dispatch function for object
• Can't change down_revision on a refresh operation.
• Can't drop table in batch mode

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

Appendix: 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 5551b5d35f)