sqlalchemy/alembic · error · ValueError

Don't know how to comma-format %r

Error message

Don't know how to comma-format %r

What it means

Raised as ValueError by format_as_comma (messaging.py:120) when the value is not None, not a str, and not an Iterable — the three cases the helper knows how to render as a comma-separated string. Any other type (int, bool, object) is rejected because the function cannot meaningfully stringify it into the expected 'a, b, c' form.

Source

Thrown at alembic/util/messaging.py:120

            subsequent_indent=indent,
        )
        if len(lines) > 1:
            for line in lines[0:-1]:
                write_outstream(sys.stdout, line, "\n")
        write_outstream(sys.stdout, lines[-1], ("\n" if newline else ""))
    if flush:
        sys.stdout.flush()


def format_as_comma(value: str | Iterable[str] | None) -> str:
    if value is None:
        return ""
    elif isinstance(value, str):
        return value
    elif isinstance(value, Iterable):
        return ", ".join(value)
    else:
        raise ValueError("Don't know how to comma-format %r" % value)

View on GitHub (pinned to 44fb345033)

Solutions

1. Pass a list, tuple, or other Iterable of strings instead of a scalar: format_as_comma(['t1','t2']).
2. If you have a single name, pass it as a string: format_as_comma('t1').
3. If None is appropriate (no items), pass None to get an empty string.
4. Add an isinstance check or convert scalars with str() before calling if a single value is intentional.

Example fix

# before
format_as_comma(3)        # ValueError
format_as_comma(True)     # ValueError
# after
format_as_comma(['t1','t2','t3'])
format_as_comma('single')
format_as_comma(None)

from collections.abc import Iterable

def safe_format_as_comma(value):
    if value is None:
        return ''
    if isinstance(value, str):
        return value
    if isinstance(value, Iterable):
        return ', '.join(value)
    raise TypeError(f'format_as_comma expects None/str/Iterable, got {type(value).__name__}')

from collections.abc import Iterable
from typing import Union
def is_comma_formattable(v) -> bool:
    return v is None or isinstance(v, (str, Iterable))

from alembic.util.messaging import format_as_comma
try:
    s = format_as_comma(value)
except ValueError:
    s = str(value)  # fallback stringification

When it happens

Trigger: Passing an integer, boolean, or arbitrary object to format_as_comma; a code path that feeds a revision count or a non-iterable config value into a messaging helper that calls format_as_comma; calling status()/format_as_comma with a single non-string scalar.

Common situations: A migration or command passes a numeric value where a list/tuple of names was expected; autogenerate diff rendering hitting an unexpected diff element type; user-facing message construction with a mis-typed argument.

Related errors

• revision %s not in map
• revision identifier %r is not a string; ensure database driv
• Can not set dispatch function for object {target!r}: key alr
• no dispatch function for object: %s
• String or text() construct expected

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