hashicorp/nomad · error

invalid ';' character in CNI arg key %q

Error message

invalid ';' character in CNI arg key %q

What it means

Validation guard in job network validation: CNI_ARGS is a ';'-separated key=val string, so a ';' embedded in an argument key would break parsing by CNI plugins or libraries. The key named in the message contains that forbidden character.

Source

Thrown at nomad/structs/structs.go:7395

			}
		}
		// Validate the cniArgs in each network resource. Make sure there are no duplicate Args in
		// different network resources or invalid characters (;) in key or value ;)
		if net.CNI != nil {
			for k, v := range net.CNI.Args {
				if cniArgKeys.Contains(k) {
					err := fmt.Errorf("duplicate CNI arg %q", k)
					mErr.Errors = append(mErr.Errors, err)
				} else {
					cniArgKeys.Insert(k)
				}
				// CNI_ARGS is a ";"-separated string of "key=val", so a ";"
				// in either key or val would confuse plugins (or libraries)
				// that parse that string.
				// Pre-validating this here protects job authors from submitting
				// a job that will most likely error later on the client anyway.
				if strings.Contains(k, ";") {
					err := fmt.Errorf("invalid ';' character in CNI arg key %q", k)
					mErr.Errors = append(mErr.Errors, err)
				}
				if strings.Contains(v, ";") {
					err := fmt.Errorf("invalid ';' character in CNI arg value %q", v)
					mErr.Errors = append(mErr.Errors, err)
				}
			}
		}

		// Validate the hostname field to be a valid DNS name. If the parameter
		// looks like it includes an interpolation value, we skip this. It
		// would be nice to validate additional parameters, but this isn't the
		// right place.
		if net.Hostname != "" && !strings.Contains(net.Hostname, "${") {
			if _, ok := dns.IsDomainName(net.Hostname); !ok {
				mErr.Errors = append(mErr.Errors, errors.New("Hostname is not a valid DNS name"))
			}
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove the ';' character from the CNI arg key
2. Replace the ';' with a safe delimiter such as '-' or '_'

When it happens

Trigger: Thrown at nomad/structs/structs.go:7395 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/e22a40252f2abdbd. Report an issue: GitHub.