CLI: Volume Parsing Differences Between WSLC and Docker

[AmelBawa-msft]

Volume Parsing Differences Between WSLC and Docker

Reference: wslc container run --volume

The current volume parser in WSLC is a lightweight implementation based on right-to-left (RTL) parsing. While it works well for common scenarios, it does not fully support all syntax variations currently accepted by Docker. Some of these gaps may be intentional, depending on how we choose to handle edge-case behavior.

Additionally, the parser currently allows container creation even though startup ultimately fails. Ideally, it should detect such situations earlier and return a descriptive error message before attempting to create the container.

---

Edge Cases That Fail in Both WSLC and Docker (Different Failure Reasons)

Although the final error surfaces from service code, the parser in WSLC produces different intermediate inputs compared to Docker.

"C:\hostPath:/containerPath:invalid_mode"
  - Docker fails because 'invalid_mode' is not a valid mode.
  - WSLC fails with ERROR_PATH_NOT_FOUND.

"C:\hostPath:/containerPath:ro:extra"
  - Docker fails due to too many colons.
  - WSLC fails with ERROR_PATH_NOT_FOUND.

"C:\hostPath:/containerPath:"
  - Docker fails because the mode is empty.
  - WSLC fails with ERROR_PATH_NOT_FOUND.

---

Edge Cases That Fail Only in WSLC (But Succeed in Docker)

It is currently unclear whether WSLC should support these cases (CC: @craigloewen-msft, @OneBlue).

"C:\hostPath"
  - Docker interpretation: 'C:\hostPath' → 'C:\hostPath'

"C:/hostPath"
  - Docker interpretation: 'C:/hostPath' → ('C:' → 'hostPath')

":"
  - Docker interpretation: ':' → ':'

"::"
  - Docker interpretation: '::' → '::'

"test"
  - Docker interpretation: 'test' → 'test'

---

Next Steps

The existing RTL parser is intentionally lightweight and sufficient for most scenarios today. However, if broader Docker compatibility becomes a goal, we could consider implementing a more robust parser that:

• Syntactically supports a larger subset of Docker volume syntax.
• Semantically aligns with Docker’s parsing behavior.
• Ensures the service layer receives consistent and correct inputs.

This would help reduce divergence in error handling and improve overall compatibility.

[github-actions]

Logs are required for review from WSL team

If this a feature request, please reply with '/feature'. If this is a question, reply with '/question'.
Otherwise, please attach logs by following the instructions below, your issue will not be reviewed unless they are added. These logs will help us understand what is going on in your machine.

How to collect WSL logs

Download and execute collect-wsl-logs.ps1 in an administrative powershell prompt:

Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/collect-wsl-logs.ps1" -OutFile collect-wsl-logs.ps1
Set-ExecutionPolicy Bypass -Scope Process -Force
.\collect-wsl-logs.ps1

The script will output the path of the log file once done.

If this is a networking issue, please use .\collect-wsl-logs.ps1 -LogProfile networking instead, following the instructions in Collect WSL logs for networking issues

Once completed please upload the output files to this GitHub issue.

See Collect WSL logs (recommended method).

If you choose to email these logs instead of attaching them to the bug, please send them to wsl-gh-logs@microsoft.com with the GitHub issue number in the subject, and include a link to your GitHub issue comment in the message body, and reply with '/emailed-logs'.

[craigloewen-msft]

It is currently unclear whether WSLC should support these cases

What are these exact cases?

The following things look identical to me so I'm not sure what's being asked:

"C:\hostPath"
  - Docker interpretation: 'C:\hostPath' → 'C:\hostPath'

"C:/hostPath"
  - Docker interpretation: 'C:/hostPath' → ('C:' → 'hostPath')

":"
  - Docker interpretation: ':' → ':'

"::"
  - Docker interpretation: '::' → '::'

"test"
  - Docker interpretation: 'test' → 'test'