docker/cli · error

invalid target port ( ): value must be an integer

Error message

invalid target port (%s): value must be an integer: %w

What it means

Thrown by PortOpt.Set (port.go:80) when the `target` (container) port value cannot be parsed as an unsigned 16-bit integer (0–65535). strconv.ParseUint(val, 10, 16) fails on non-numeric, out-of-range, or empty values; the underlying NumError is unwrapped via errors.As and wrapped into this message.

Solutions

1. Provide an integer between 0 and 65535 for target: `--publish target=80`.
2. Ensure the value is a plain decimal integer with no units or sign for negative.
3. Pre-validate with `strconv.ParseUint(val, 10, 16)`.
4. Remember target= is the in-container port; published= is the host port.

Example fix

// before
--publish published=8080,target=80http
// after
--publish published=8080,target=80

// Validate the target port as a uint16 before Set.
if _, err := strconv.ParseUint(targetVal, 10, 16); err != nil {
    return fmt.Errorf("target port %q must be an integer 0-65535", targetVal)
}

When it happens

Trigger: Passing `--publish target=abc`, `target=70000` (exceeds uint16), `target=-1`, or `target=` (empty). ParseUint returns an error, errors.As extracts the NumError, and line 80 reports it.

Common situations: Typos, values exceeding 65535, negative numbers, empty strings from variable expansion, or confusion between the target (container) and published (host) port slots.

Related errors

• invalid field
• invalid protocol value
• invalid publish mode value
• invalid published port
• invalid field key

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/84e1d65415cbbfc6. Report an issue: GitHub.

Appendix: source

Thrown at opts/swarmopts/port.go:80

					pConfig.Protocol = proto
				default:
					return fmt.Errorf("invalid protocol value '%s'", val)
				}
			case portOptMode:
				switch swarm.PortConfigPublishMode(val) {
				case swarm.PortConfigPublishModeIngress, swarm.PortConfigPublishModeHost:
					pConfig.PublishMode = swarm.PortConfigPublishMode(val)
				default:
					return fmt.Errorf("invalid publish mode value (%s): must be either '%s' or '%s'", val, swarm.PortConfigPublishModeIngress, swarm.PortConfigPublishModeHost)
				}
			case portOptTargetPort:
				tPort, err := strconv.ParseUint(val, 10, 16)
				if err != nil {
					var numErr *strconv.NumError
					if errors.As(err, &numErr) {
						err = numErr.Err
					}
					return fmt.Errorf("invalid target port (%s): value must be an integer: %w", val, err)
				}

				pConfig.TargetPort = uint32(tPort)
			case portOptPublishedPort:
				pPort, err := strconv.ParseUint(val, 10, 16)
				if err != nil {
					var numErr *strconv.NumError
					if errors.As(err, &numErr) {
						err = numErr.Err
					}
					return fmt.Errorf("invalid published port (%s): value must be an integer: %w", val, err)
				}

				pConfig.PublishedPort = uint32(pPort)
			default:
				return fmt.Errorf("invalid field key: %s", key)
			}
		}

View on GitHub (pinned to 4f84911bfe)