docker/cli · error

docker endpoint configuration is required

Error message

docker endpoint configuration is required

What it means

createNewContext requires a docker endpoint configuration (opts.endpoint) before it will build the context's endpoint metadata. In current code the no-endpoint/no-from case is routed to copying the current context, so this guard fires when creation reaches createNewContext with an empty --docker spec — a context without a docker endpoint would be unusable.

Source

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

	}
	switch {
	case opts.from == "" && opts.endpoint == nil:
		err = createFromExistingContext(s, name, dockerCLI.CurrentContext(), opts)
	case opts.from != "":
		err = createFromExistingContext(s, name, opts.from, opts)
	default:
		err = createNewContext(s, name, opts)
	}
	if err == nil {
		_, _ = fmt.Fprintln(dockerCLI.Out(), name)
		_, _ = fmt.Fprintf(dockerCLI.Err(), "Successfully created context %q\n", name)
	}
	return err
}

func createNewContext(contextStore store.ReaderWriter, name string, opts createOptions) error {
	if opts.endpoint == nil {
		return errors.New("docker endpoint configuration is required")
	}
	dockerEP, dockerTLS, err := getDockerEndpointMetadataAndTLS(contextStore, opts.endpoint)
	if err != nil {
		return fmt.Errorf("unable to create docker endpoint config: %w", err)
	}
	contextMetadata := store.Metadata{
		Endpoints: map[string]any{
			docker.DockerEndpoint: dockerEP,
		},
		Metadata: command.DockerContext{
			Description:      opts.description,
			AdditionalFields: opts.metaData,
		},
		Name: name,
	}
	contextTLSData := store.ContextTLSData{}
	if dockerTLS != nil {
		contextTLSData.Endpoints = map[string]store.EndpointTLSData{

View on GitHub (pinned to e9452d6e78)

Solutions

1. Provide an endpoint: `docker context create mycontext --docker "host=ssh://user@host"` (or host=tcp://... / unix://...).
2. To duplicate an existing context instead, use `--from <context>` or omit both flags on a recent CLI (copies the current context).
3. In scripts, validate the endpoint variable is non-empty before passing --docker.

Example fix

# before
docker context create remote
# (older CLI: docker endpoint configuration is required)
# after
docker context create remote --docker "host=ssh://deploy@prod-server"

When it happens

Trigger: `docker context create <name>` paths that reach createNewContext (cli/command/context/create.go:86) with opts.endpoint == nil — e.g. flag parsing produced an empty endpoint map, or programmatic callers invoking createNewContext directly without endpoint config.

Common situations: Scripts building the --docker argument from an empty variable (`--docker "$OPTS"` with OPTS unset can yield an empty spec); older docker CLI versions where omitting both --docker and --from was an error instead of copying the current context; library consumers calling the create path with incomplete options.

Related errors

• conflicting options: cannot specify both --host and --contex
• no context specified
• unrecognized config key:
• user agent cannot be blank
• context metadata is not a valid DockerContext

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/9e8b855debba4976.json. Report an issue: GitHub.