{"record":{"id":"57866f3abdefef7a","repo":"Unity-Technologies/ml-agents","slug":"the-communication-api-version-is-not-compatible-be","errorCode":null,"errorMessage":"The communication API version is not compatible between Unity and python. Python API: {UnityEnvironment.API_VERSION}, Unity API: {unity_com_ver}.\n Please find the versions that work best together from our release page.\nhttps://github.com/Unity-Technologies/ml-agents/releases","messagePattern":"The communication API version is not compatible between Unity and python\\. Python API: (.+?), Unity API: (.+?)\\.\n Please find the versions that work best together from our release page\\.\nhttps://github\\.com/Unity-Technologies/ml-agents/releases","errorType":"exception","errorClass":"UnityEnvironmentException","httpStatus":null,"severity":"error","filePath":"ml-agents-envs/mlagents_envs/environment.py","lineNumber":83,"sourceCode":"    #  * 1.3.0 - support action spaces with both continuous and discrete actions.\n    #  * 1.4.0 - support training analytics sent from python trainer to the editor.\n    #  * 1.5.0 - support variable length observation training and multi-agent groups.\n    API_VERSION = \"1.5.0\"\n\n    # Default port that the editor listens on. If an environment executable\n    # isn't specified, this port will be used.\n    DEFAULT_EDITOR_PORT = 5004\n\n    # Default base port for environments. Each environment will be offset from this\n    # by it's worker_id.\n    BASE_ENVIRONMENT_PORT = 5005\n\n    # Command line argument used to pass the port to the executable environment.\n    _PORT_COMMAND_LINE_ARG = \"--mlagents-port\"\n\n    @staticmethod\n    def _raise_version_exception(unity_com_ver: str) -> None:\n        raise UnityEnvironmentException(\n            f\"The communication API version is not compatible between Unity and python. \"\n            f\"Python API: {UnityEnvironment.API_VERSION}, Unity API: {unity_com_ver}.\\n \"\n            f\"Please find the versions that work best together from our release page.\\n\"\n            \"https://github.com/Unity-Technologies/ml-agents/releases\"\n        )\n\n    @staticmethod\n    def _check_communication_compatibility(\n        unity_com_ver: str, python_api_version: str, unity_package_version: str\n    ) -> bool:\n        unity_communicator_version = StrictVersion(unity_com_ver)\n        api_version = StrictVersion(python_api_version)\n        if unity_communicator_version.version[0] == 0:\n            if (\n                unity_communicator_version.version[0] != api_version.version[0]\n                or unity_communicator_version.version[1] != api_version.version[1]\n            ):\n                # Minor beta versions differ.","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents-envs/mlagents_envs/environment.py#L65-L101","documentation":"Static method UnityEnvironment._raise_version_exception throws UnityEnvironmentException when the communication API version reported by the Unity side of the communicator does not match UnityEnvironment.API_VERSION on the Python side. ml-agents requires both halves to speak the same protocol version. It directs the user to the release notes to find matching versions.","triggerScenarios":"Launching or connecting to a Unity build created with an ml-agents release whose communicator API version differs from the installed mlagents_envs Python package; the handshake compares unity_com_ver against UnityEnvironment.API_VERSION and calls this method on mismatch.","commonSituations":"pip-installed mlagents at one version while the Unity project uses the ML-Agents package/commlib of another release; upgrading only the Python side; connecting an old prebuilt environment to a newly upgraded training stack.","solutions":["Align versions: install the Python package matching the Unity ML-Agents release (e.g. pip install mlagents==<matching-release>).","Rebuild the Unity executable with the same ML-Agents release as the Python side.","Check the ml-agents releases page for the version compatibility table.","Pin both sides (requirements.txt and Unity PackageManifest) to the same release to avoid drift."],"exampleFix":"// before (shell)\npip install mlagents  # latest python, but Unity build uses release 18\n# UnityEnvironmentException: API version not compatible\n\n// after (shell)\npip install mlagents==0.30.0  # matches Unity ML-Agents release 18","handlingStrategy":"validation","validationCode":"from mlagents_envs.environment import UnityEnvironment\nimport mlagents\nprint('Python API version:', UnityEnvironment.API_VERSION)\nprint('mlagents package:', mlagents.__version__)\n# Confirm this matches the ML-Agents release used to build the Unity executable.","typeGuard":null,"tryCatchPattern":"from mlagents_envs.exception import UnityEnvironmentException\ntry:\n    env = UnityEnvironment(file_name='env.x86_64')\nexcept UnityEnvironmentException as e:\n    if 'API version is not compatible' in str(e):\n        print('Reinstall mlagents at the version matching your Unity build.')\n    raise","preventionTips":["Pin mlagents in requirements.txt to the release matching your Unity ML-Agents package.","Check the ml-agents releases page compatibility table before upgrading either side.","Rebuild Unity executables whenever you upgrade the Python side.","Log UnityEnvironment.API_VERSION at training startup for debugging."],"tags":["version-mismatch","protocol","ml-agents"],"backgroundTag":"api-version-mismatch","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}