sqlalchemy/alembic · error · ValueError

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

Error message

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

What it means

Config._get_file_separator_char raises ValueError when the path_separator (or deprecated version_path_separator) option in alembic.ini has a value outside the allowed set. The value must be one of 'space', 'newline', 'os', ':', or ';' so Alembic knows how to split multi-value path strings.

Solutions

1. Set path_separator to one of the allowed values: 'space', 'newline', 'os', ':', or ';' (os uses the platform separator).
2. Remove the path_separator line entirely to get the legacy deprecation warning rather than a hard error.
3. Use 'os' for cross-platform path lists matching the OS path separator.

Example fix

# before (alembic.ini)
path_separator = comma

# after
path_separator = os

ALLOWED = {'space', 'newline', 'os', ':', ';'}
value = config.get_main_option('path_separator')
if value is not None and value not in ALLOWED:
    raise ValueError(f'Invalid path_separator: {value}; allowed: {ALLOWED}')

def is_valid_separator(value: str) -> bool:
    return value in {'space', 'newline', 'os', ':', ';'}

When it happens

Trigger: Setting path_separator = comma (or any other unsupported token) in the [alembic] section of alembic.ini; using version_locations or prepend_sys_path with a separator value Alembic does not recognize.

Common situations: Developers assuming comma is a valid separator; copy-pasting a config snippet from an outdated tutorial; migrating an old config that relied on legacy space/comma splitting and adding a wrong explicit value.

Related errors

• A plugin named is already registered
• Can't find Python file
• can't return inspector as this AutogenContext has no…
• Connection, url, or dialect_name is required.
• Duplicate table keys across multiple MetaData objects

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

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