[Bug]: The reuse hash might be unstable across Testcontainers versions

[0xced]

Testcontainers version

4.7.0

Using the latest Testcontainers version?

Yes

Host OS

macOS

Host arch

ARM64

.NET version

8.0.415

Docker version

Client:
 Version:           28.3.3
 API version:       1.51
 Go version:        go1.24.5
 Git commit:        980b856
 Built:             Fri Jul 25 11:33:03 2025
 OS/Arch:           darwin/arm64
 Context:           orbstack

Server: Docker Engine - Community
 Engine:
  Version:          28.3.3
  API version:      1.51 (minimum version 1.24)
  Go version:       go1.24.5
  Git commit:       bea959c
  Built:            Fri Jul 25 11:34:22 2025
  OS/Arch:          linux/arm64
  Experimental:     false
 containerd:
  Version:          v2.1.4
  GitCommit:        75cb2b7193e4e490e9fbdc236c0e811ccaba3376
 runc:
  Version:          1.3.1
  GitCommit:        e6457afc48eff1ce22dece664932395026a7105e
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

Docker info

not relevant

What happened?

After upgrading from Testcontainers.MsSql version 4.6.0 to version 4.7.0 I got this error:

Docker.DotNet.DockerApiException: Docker API responded with status code=Conflict, response={"message":"Conflict. The container name \"/MySqlServerContainer\" is already in use by container \"65f28cbf99432ce26924f2024cdc030b8f198962543f40fc65be4accdb052dce\". You have to remove (or rename) that container to be able to reuse that name."}

This is the error you get when the reuse hash changes, but there was no reason for the reuse hash to change!

So I ran under a debugger and noticed why the reuse hash changed. Here's an excerpt from the input JSON which goes through SHA1 hashing, indented for readability.

With version 4.6.0:

{
  "Command": [],
  "Environments": {
    "SQLCMDPASSWORD": "yourStrong(!)Password",
    "MSSQL_SA_PASSWORD": "yourStrong(!)Password",
    "SQLCMDUSER": "sa",
    "SQLCMDDBNAME": "master",
    "ACCEPT_EULA": "Y"
  },
  "ExposedPorts": {
    "1433": "1433"
  }
}

With version 4.7.0

{
  "Command": [],
  "Environments": {
    "ACCEPT_EULA": "Y",
    "SQLCMDDBNAME": "master",
    "SQLCMDUSER": "sa",
    "MSSQL_SA_PASSWORD": "yourStrong(!)Password",
    "SQLCMDPASSWORD": "yourStrong(!)Password"
  },
  "ExposedPorts": {
    "1433": "1433"
  }
}

Notice how the Environments dictionary is the same from a JSON point of view (i.e. same keys and same values) but is different for hashing since the keys are not in the exact same order.

Relevant log output

Additional information

I don't know yet what's the best way to fix this. Probably the easiest way is to order all dictionary keys alphabetically during JSON serialization.

[HofmeisterAn]

Interesting observation. I think this comes from #1506. It slightly changes how we merge the dictionaries.

testcontainers-dotnet/src/Testcontainers/Builders/BuildConfiguration.cs

Lines 122 to 149 in 18cf3a8

	public static IReadOnlyDictionary<TKey, TValue> Combine<TKey, TValue>(
	IReadOnlyDictionary<TKey, TValue> oldValue,
	IReadOnlyDictionary<TKey, TValue> newValue)
	{
	if (newValue == null && oldValue == null)
	{
	return new ReadOnlyDictionary<TKey, TValue>(new Dictionary<TKey, TValue>());
	}
	if (newValue == null || oldValue == null)
	{
	return newValue ?? oldValue;
	}
	var result = new Dictionary<TKey, TValue>(oldValue.Count + newValue.Count);
	foreach (var kvp in oldValue)
	{
	result[kvp.Key] = kvp.Value;
	}
	foreach (var kvp in newValue)
	{
	result[kvp.Key] = kvp.Value;
	}
	return new ReadOnlyDictionary<TKey, TValue>(result);
	}

I don't expect it to happen often, but having a more robust serialization mechanism would be better. A custom JSON converter similar to JsonIgnoreRuntimeResourceLabels is probably enough.

[0xced]

Yes, I already started working on a similar JSON converter. A pull request will be coming soon. 😉