What causes "docker endpoint configuration is required" in docker/cli?

Supply --docker with at least the host: `docker context create myctx --docker host=unix:///var/run/docker.sock`.

docker endpoint configuration is required

Error message

docker endpoint configuration is required

What it means

Returned by createNewContext when opts.endpoint is nil, i.e. the user created a context without a --docker endpoint and not from an existing context. A docker context requires a docker endpoint (host + optional TLS material); without it the context is useless, so creation is aborted at create.go:87-89. The switch in runCreate only calls createNewContext in the default branch (no --from, endpoint not pre-set).

Solutions

Supply --docker with at least the host: `docker context create myctx --docker host=unix:///var/run/docker.sock`.
Or base it on an existing context: `docker context create myctx --from default`.
For TLS endpoints add ca/cert/key in the --docker string.

Example fix

// before
docker context create myctx

// after
docker context create myctx --docker host=unix:///var/run/docker.sock

Defensive patterns

Strategy: validation

Validate before calling

func validateCreate(name, from string, endpoint map[string]string) error {
    if from == "" && len(endpoint) == 0 {
        return errors.New("docker endpoint configuration is required")
    }
    return nil
}

Prevention

Always pass --docker host=... when creating a fresh context.
If cloning, use --from <existing> instead.
Default the endpoint in your context-creation helper to avoid empty invocations.

When it happens

Trigger: `docker context create myctx` with no --docker and no --from. opts.endpoint stays nil and runCreate routes to createNewContext which errors.

Common situations: Forgetting the --docker flag on first context creation. Assuming a default host is used (it is not for explicit contexts). Misreading docs and omitting the endpoint.

Related errors

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

Appendix: 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 4f84911bfe)