"Error: Unknown option" for option set in daml.yaml?

Background

According to the docs, when running daml start I can set options in the daml.yaml file for the Sandbox, Navigator, JSON API, and script runner:

• sandbox-options: a list of options that will be passed to Sandbox in daml start.
• navigator-options: a list of options that will be passed to Navigator in daml start.
• json-api-options: a list of options that will be passed to the HTTP JSON API in daml start.
• script-options: a list of options that will be passed to the Daml script runner when running the init-script as part of daml start.

Problem

However, sometimes when I try to set options in the daml.yaml file, I get this error:

Error: Unknown option --some-option=some-value

For example, the following in the daml.yaml will fail when running daml start…

json-api-options: 
  - --http-port=7575
  - --log-level=DEBUG
  - --max-inbound-message-size=9000000

…because of the --http-port. But --http-port is definitely an option for the http-json-binary. Why is it reported as an “unknown option?”

In the case of the --http-port example, it fails because daml start is already passing a value for --http-port to the http-json-binary. It is passing a value because daml start has a command line option --json-api-port. The invocation of the http-json-binary has --http-port included twice. The second one (from the daml.yaml file) is considered an “Unknown option” because the --http-port was already set.

You can see the same behavior if you add this to the daml.yaml file:

navigator-options:
  - --port=7501