What causes "cannot use --docker flag when --from is set" in docker/cli?

To clone, drop --docker: `docker context create new --from default`.

cannot use --docker flag when --from is set

Error message

cannot use --docker flag when --from is set

What it means

Returned by createFromExistingContext when --from is set AND --docker is also provided. When cloning from another context the endpoint is taken wholesale from the source, so specifying --docker would conflict; the CLI forbids the combination at create.go:132-135. The user must choose to clone OR to define a fresh endpoint.

Solutions

To clone, drop --docker: `docker context create new --from default`.
To set a custom endpoint, drop --from and use --docker: `docker context create new --docker host=...`.
If you need to clone then modify, clone first and use `docker context update` (or remove + recreate).

Example fix

// before
docker context create new --from default --docker host=tcp://host:2376

// after
docker context create new --from default

Defensive patterns

Strategy: validation

Validate before calling

func validateContextCreate(from string, endpoint map[string]string) error {
    if from != "" && len(endpoint) != 0 {
        return errors.New("cannot use --docker flag when --from is set")
    }
    return nil
}

Prevention

Treat --from and --docker as mutually exclusive in wrapper tooling.
To clone-then-modify, clone first then update separately.
Document the either/or rule in context management scripts.

When it happens

Trigger: `docker context create new --from default --docker host=tcp://host:2376`. opts.from != "" and len(opts.endpoint) != 0.

Common situations: Trying to clone a context while overriding its host in one step (not supported). Scripts templating both flags. Confusion about whether --from copies endpoints.

Related errors

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

Appendix: source

Thrown at cli/command/context/create.go:134

	return contextStore.ResetTLSMaterial(name, &contextTLSData)
}

func checkContextNameForCreation(s store.Reader, name string) error {
	if err := store.ValidateContextName(name); err != nil {
		return err
	}
	if _, err := s.GetMetadata(name); !errdefs.IsNotFound(err) {
		if err != nil {
			return fmt.Errorf("error while getting existing contexts: %w", err)
		}
		return fmt.Errorf("context %q already exists", name)
	}
	return nil
}

func createFromExistingContext(s store.ReaderWriter, name string, fromContextName string, opts createOptions) error {
	if len(opts.endpoint) != 0 {
		return errors.New("cannot use --docker flag when --from is set")
	}
	reader := store.Export(fromContextName, &descriptionDecorator{
		Reader:      s,
		description: opts.description,
	})
	defer reader.Close()
	return store.Import(name, s, reader)
}

type descriptionDecorator struct {
	store.Reader
	description string
}

func (d *descriptionDecorator) GetMetadata(name string) (store.Metadata, error) {
	c, err := d.Reader.GetMetadata(name)
	if err != nil {
		return c, err

View on GitHub (pinned to 4f84911bfe)