docker/cli · error

unknown type: : must be one of

Error message

unknown type: %q: must be one of "%s"

What it means

Returned by 'docker inspect --type <X>' when <X> is non-empty but not one of the recognized object types. The switch at inspect.go:90-96 falls through to default for anything not in {config, container, image, network, node, plugin, secret, service, task, volume}.

Solutions

1. Use one of the listed types exactly (singular): container, image, network, node, plugin, secret, service, task, volume, config.
2. Run 'docker inspect --help' to see the types supported by your CLI version.
3. Drop --type to let inspect search across all object kinds.

Example fix

# before
docker inspect --type containers myid

# after
docker inspect --type container myid
# -or-
docker inspect myid

// Validate type against known set
known := map[string]bool{"config": true, "container": true, "image": true, "network": true, "node": true, "plugin": true, "secret": true, "service": true, "task": true, "volume": true}
if !known[opts.objectType] {
    return fmt.Errorf("unknown type %q", opts.objectType)
}

func isKnownInspectType(t string) bool {
	switch t {
	case "", typeConfig, typeContainer, typeImage, typeNetwork, typeNode, typePlugin, typeSecret, typeService, typeTask, typeVolume:
		return true
	}
	return false
}

When it happens

Trigger: Running 'docker inspect --type pod <id>' or --type containers (plural), --type image-file, etc. Any unrecognized type token reaches the default branch.

Common situations: Using a Kubernetes term (pod, deployment); plural form (containers instead of container); typo; version skew where a type exists in a newer CLI but not this one.

Related errors

• type is empty: must be one of
• error: no such object
• error reading from STDIN: data is empty
• config file is required
• cannot supply extra formatting options to the pretty…

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

Appendix: source

Thrown at cli/command/system/inspect.go:95

	flags := cmd.Flags()
	flags.StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp)
	flags.StringVar(&opts.objectType, "type", "", "Only inspect objects of the given type")
	flags.BoolVarP(&opts.size, "size", "s", false, "Display total file sizes if the type is container")

	_ = cmd.RegisterFlagCompletionFunc("type", completion.FromList(allTypes...))

	return cmd
}

func runInspect(ctx context.Context, dockerCli command.Cli, opts inspectOptions) error {
	var elementSearcher inspect.GetRefFunc
	switch opts.objectType {
	case "", typeConfig, typeContainer, typeImage, typeNetwork, typeNode,
		typePlugin, typeSecret, typeService, typeTask, typeVolume:
		elementSearcher = inspectAll(ctx, dockerCli, opts.size, opts.objectType)
	default:
		return fmt.Errorf(`unknown type: %q: must be one of "%s"`, opts.objectType, strings.Join(allTypes, `", "`))
	}
	return inspect.Inspect(dockerCli.Out(), opts.ids, opts.format, elementSearcher)
}

func inspectContainers(ctx context.Context, dockerCli command.Cli, getSize bool) inspect.GetRefFunc {
	return func(ref string) (any, []byte, error) {
		res, err := dockerCli.Client().ContainerInspect(ctx, ref, client.ContainerInspectOptions{Size: getSize})
		if err != nil {
			return nil, nil, err
		}
		return res.Container, res.Raw, err
	}
}

func inspectImages(ctx context.Context, dockerCli command.Cli) inspect.GetRefFunc {
	return func(ref string) (any, []byte, error) {
		var buf bytes.Buffer
		resp, err := dockerCli.Client().ImageInspect(ctx, ref, client.ImageInspectWithRawResponse(&buf))

View on GitHub (pinned to 4f84911bfe)