{"id":"d84af8c6229c0346","repo":"sqlalchemy/alembic","slug":"revision-identifier-r-is-not-a-string-ensure-dat","errorCode":null,"errorMessage":"revision identifier %r is not a string; ensure database driver settings are correct","messagePattern":"revision identifier %r is not a string; ensure database driver settings are correct","errorType":"exception","errorClass":"RevisionError","httpStatus":null,"severity":"error","filePath":"alembic/script/revision.py","lineNumber":752,"sourceCode":"                    [resolved_target],\n                    include_dependencies=include_dependencies,\n                )\n            )\n            .intersection(resolved_test_against_revs)\n        )\n\n    def _resolve_revision_number(\n        self, id_: _GetRevArg | None\n    ) -> tuple[tuple[str, ...], str | None]:\n        branch_label: str | None\n        if isinstance(id_, str) and \"@\" in id_:\n            branch_label, id_ = id_.split(\"@\", 1)\n\n        elif id_ is not None and (\n            (isinstance(id_, tuple) and id_ and not isinstance(id_[0], str))\n            or not isinstance(id_, (str, tuple))\n        ):\n            raise RevisionError(\n                \"revision identifier %r is not a string; ensure database \"\n                \"driver settings are correct\" % (id_,)\n            )\n\n        else:\n            branch_label = None\n\n        # ensure map is loaded\n        self._revision_map\n        if id_ == \"heads\":\n            if branch_label:\n                return (\n                    self.filter_for_lineage(self.heads, branch_label),\n                    branch_label,\n                )\n            else:\n                return self._real_heads, branch_label\n        elif id_ == \"head\":","sourceCodeStart":734,"sourceCodeEnd":770,"githubUrl":"https://github.com/sqlalchemy/alembic/blob/44fb3450330204b222ff05135e1fbbbdb28c44db/alembic/script/revision.py#L734-L770","documentation":"Raised by _resolve_revision_number when the supplied identifier is not a string (and not a tuple of strings). The message's 'database driver settings' hint reflects the classic cause: the value read from the database's version table came back as a non-string (e.g., bytes, int, or a custom type) because the version column type / driver doesn't return str. It is a RevisionError.","triggerScenarios":"The version_num column in alembic_version returning bytes (e.g., some MySQL/psycopg2 configs), an integer, or None-wrapped objects; passing a non-string programmatically into upgrade/downgrade; SQLAlchemy column type mismatch on the version table.","commonSituations":"Switching database drivers (e.g., to a driver that returns bytes for VARCHAR); custom version_table schema where the column type isn't String; older alembic_version tables migrated to a new DB engine with different type coercion.","solutions":["Check the alembic_version table column type and ensure version_num is a String/VARCHAR; alter the column if the driver coerces it to bytes or int.","Update or correct the database driver / SQLAlchemy version so VARCHAR columns return Python str.","If you pass ids programmatically, coerce to str before calling the API."],"exampleFix":"# before (version_num column returns bytes)\n# ALTER TABLE alembic_version ALTER COLUMN version_num TYPE varchar\n# after\n# ensure driver returns str; e.g. use psycopg2 (not a bytes-returning driver)","handlingStrategy":"validation","validationCode":"from alembic.runtime.migration import MigrationContext\nwith engine.begin() as conn:\n    ctx = MigrationContext.configure(conn)\n    current = ctx.get_current_revision()\nif not isinstance(current, str):\n    raise RuntimeError(\n        'version column returned %r, not str; check driver/column type'\n        % type(current)\n    )","typeGuard":"def is_str_revision(value) -> bool:\n    return value is None or isinstance(value, str)","tryCatchPattern":"from alembic.script.revision import RevisionError\ntry:\n    script.get_revision(current)\nexcept RevisionError as e:\n    if 'not a string' in str(e):\n        # fix the version table column type / driver, then retry\n        ...","preventionTips":["Ensure the alembic_version.version_num column is a String/VARCHAR type.","Use a driver that returns str for character columns.","Validate the current revision type before passing it into alembic APIs."],"tags":["database-driver","type-mismatch","version-table","alembic"],"analyzedSha":"44fb3450330204b222ff05135e1fbbbdb28c44db","analyzedAt":"2026-08-04T19:57:10.248Z","schemaVersion":2}