docker/cli · error

context name cannot be empty

Error message

context name cannot be empty

What it means

Returned by ValidateContextName when the provided name is the empty string. Context names are identifiers used in directory paths and CLI commands, so an empty name is rejected before any filesystem operation.

Solutions

1. Provide a non-empty context name, e.g. 'docker context create my-remote --docker host=ssh://user@host'.
2. Ensure any variable used for the name is set and non-empty before invoking the command.
3. Validate the name upstream with a non-empty check.

Example fix

# before
docker context create "" --docker host=ssh://user@host
# after
docker context create remote-prod --docker host=ssh://user@host

if name := strings.TrimSpace(ctxName); name == "" {
    return errors.New("context name must not be empty")
}

func isNonEmptyName(s string) bool { return strings.TrimSpace(s) != "" }

When it happens

Trigger: Calling 'docker context create' (or ValidateContextName directly) with an empty name argument. A script that builds the name from an unset variable.

Common situations: A CI step parameterizes the context name but the variable is empty. Accidentally hitting enter on a prompt without typing a name.

Related errors

• "default" is a reserved context name
• context name is invalid, names are validated against regexp
• docker endpoint configuration is required
• unrecognized config key
• failed to retrieve context tls info: ca.pem seems invalid

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

Appendix: source

Thrown at cli/context/store/store.go:218

// GetTLSData reads, and returns the content of the given fileName for an endpoint.
// It returns an errdefs.ErrNotFound if the file was not found.
func (s *ContextStore) GetTLSData(contextName, endpointName, fileName string) ([]byte, error) {
	return s.tls.getData(contextName, endpointName, fileName)
}

// GetStorageInfo returns the paths where the Metadata and TLS data are stored
// for the context.
func (s *ContextStore) GetStorageInfo(contextName string) StorageInfo {
	return StorageInfo{
		MetadataPath: s.meta.contextDir(contextdirOf(contextName)),
		TLSPath:      s.tls.contextDir(contextName),
	}
}

// ValidateContextName checks a context name is valid.
func ValidateContextName(name string) error {
	if name == "" {
		return errors.New("context name cannot be empty")
	}
	if name == "default" {
		return errors.New(`"default" is a reserved context name`)
	}
	if !isValidName(name) {
		return fmt.Errorf("context name %q is invalid, names are validated against regexp %q", name, validNameFormat)
	}
	return nil
}

// validNameFormat is used as part of errors for invalid context-names.
// We should consider making this less technical ("must start with "a-z",
// and only consist of alphanumeric characters and separators").
const validNameFormat = `^[a-zA-Z0-9][a-zA-Z0-9_.+-]+$`

// isValidName checks if the context-name is valid ("^[a-zA-Z0-9][a-zA-Z0-9_.+-]+$").
//
// Names must start with an alphanumeric character (a-zA-Z0-9), followed by

View on GitHub (pinned to 4f84911bfe)