sqlalchemy/alembic · error · ValueError

'%s' is not a valid value for %s; expected 'space', 'newline

Error message

'%s' is not a valid value for %s; expected 'space', 'newline', 'os', ':', ';'

What it means

Alembic's Config splits the version_locations / path_separator config values using a separator named in alembic.ini. Only 'space', 'newline', 'os' (os.pathsep), ':', and ';' are accepted; anything else cannot be mapped to a split character and raises.

Source

Thrown at alembic/config.py:545

        for name in names:
            separator = self.get_main_option(name)
            if separator is not None:
                break
        else:
            return None

        split_on_path = {
            "space": " ",
            "newline": "\n",
            "os": os.pathsep,
            ":": ":",
            ";": ";",
        }

        try:
            sep = split_on_path[separator]
        except KeyError as ke:
            raise ValueError(
                "'%s' is not a valid value for %s; "
                "expected 'space', 'newline', 'os', ':', ';'"
                % (separator, name)
            ) from ke
        else:
            if name == "version_path_separator":
                util.warn_deprecated(
                    "The version_path_separator configuration parameter "
                    "is deprecated; please use path_separator"
                )
            return sep

    def get_version_locations_list(self) -> list[str] | None:

        version_locations_str = self.file_config.get(
            self.config_ini_section, "version_locations", fallback=None
        )

View on GitHub (pinned to 44fb345033)

Solutions

1. Set path_separator to one of: space, newline, os, :, ;.
2. Use 'os' to match the host's native path separator.
3. If you need comma-separated locations, switch to newline-separated (multiline value) which is the most portable.

Example fix

// before
# alembic.ini
path_separator = comma
version_locations = a,b,c
// after
# alembic.ini
path_separator = newline
version_locations =
    a
    b
    c

allowed = {"space", "newline", "os", ":", ";"}
sep = config.get_main_option("path_separator")
if sep is not None and sep not in allowed:
    raise ValueError(f"path_separator must be one of {sorted(allowed)}, got {sep!r}")

def is_valid_separator(v) -> bool:
    return v in {"space", "newline", "os", ":", ";"}

When it happens

Trigger: Setting path_separator (or the deprecated version_path_separator) in alembic.ini / the config file to a value outside the allowed set, e.g. path_separator = comma, path_separator = |, or path_separator = ,.

Common situations: A user copies a config snippet from a tutorial that used a non-standard separator; a typo in alembic.ini; migrating from an older alembic that only knew version_path_separator.

Related errors

• Duplicate table keys across multiple MetaData objects: %s
• recreate may be one of 'auto', 'always', or 'never'.
• No context has been configured yet.
• Connection, url, or dialect_name is required.
• A plugin named {name} is already registered

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