Heuristic:CARLA simulator Carla Client Server Version Match
| Knowledge Sources | |
|---|---|
| Domains | Debugging, Infrastructure |
| Last Updated | 2026-02-15 07:00 GMT |
Overview
Ensure the CARLA Python API client version matches the CARLA server version to avoid subtle incompatibilities and undefined behavior.
Description
CARLA uses an RPC-based client-server architecture where the Python API (client) communicates with the simulator (server) over a network protocol. The client and server exchange version strings on connection, and a mismatch triggers a warning in the C++ runtime. Version mismatches can cause: serialization errors, missing API methods, changed behavior of existing methods, or silent data corruption. The version check happens automatically inside Simulator.cpp:37-47 via `ValidateVersions()`.
Usage
Use this heuristic whenever debugging connection issues or unexpected behavior between the Python client and CARLA server. Also apply when upgrading either the server or client independently.
The Insight (Rule of Thumb)
- Action: Always use matching client and server versions. Verify with `client.get_client_version()` and `client.get_server_version()`.
- Value: Both version strings must be identical (e.g., both "0.10.0").
- Trade-off: Requires rebuilding the Python API wheel whenever the server is updated, but prevents hard-to-debug compatibility issues.
Reasoning
The RPC protocol serializes C++ structs using rpclib's msgpack serialization. When struct layouts change between versions (new fields, reordered fields, changed types), the client and server will silently misinterpret data. The warning at Simulator.cpp:41-46 is intentionally non-fatal to allow testing, but production use should always match versions.
// LibCarla/source/carla/client/detail/Simulator.cpp:37-47
static void ValidateVersions(Client &client) {
const auto vc = client.GetClientVersion();
const auto vs = client.GetServerVersion();
if (vc != vs) {
log_warning(
"Version mismatch detected: You are trying to connect to a simulator",
"that might be incompatible with this API");
log_warning("Client API version =", vc);
log_warning("Simulator API version =", vs);
}
}