docker/cli · error

failed to rename container

Error message

failed to rename container: %w

What it means

Thrown by newRenameCommand when the client.ContainerRename API call returns an error. The underlying error is wrapped, so it typically carries a daemon message such as 'container already exists', 'no such container', or 'conflict'.

Solutions

1. Confirm the source exists: docker ps -a --filter name=^/old$
2. Pick a unique new name: docker ps -a --filter name=^/new$ (should be empty)
3. Remove or rename the conflicting container first
4. Use valid characters: alphanumeric, underscore, dot, hyphen

Example fix

# before
docker rename oldctr existingctr  # existingctr already in use
# after
docker rename oldctr newctr

// Confirm source exists and target name is free before renaming.
if _, err := cli.ContainerInspect(ctx, oldName); err != nil {
    return fmt.Errorf("source container missing: %w", err)
}
if _, err := cli.ContainerInspect(ctx, newName); err == nil {
    return fmt.Errorf("target name %q already in use", newName)
}

if _, err := cli.ContainerRename(ctx, oldName, client.ContainerRenameOptions{NewName: newName}); err != nil {
    if strings.Contains(err.Error(), "already exists") {
        // retry with a unique suffix
    }
    return fmt.Errorf("rename failed: %w", err)
}

When it happens

Trigger: Running `docker rename old new` where 'old' does not exist, 'new' is already taken, the name is invalid, or the daemon rejects the request (permission, name conflict with an existing container ID prefix).

Common situations: Target name already used by another container; source name typo; invalid characters in the new name; daemon in read-only/swarm-worker mode; name conflict after a partial cleanup.

Related errors

• failed to start containers
• cannot attach to a stopped container, start it first
• cannot attach to a paused container, unpause it first
• cannot attach to a restarting container, wait until it is…
• conflicting options: --no-pause and --pause cannot be used…

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

Appendix: source

Thrown at cli/command/container/rename.go:25

	"github.com/docker/cli/cli/command"
	"github.com/docker/cli/cli/command/completion"
	"github.com/moby/moby/client"
	"github.com/spf13/cobra"
)

// newRenameCommand creates a new cobra.Command for "docker container rename".
func newRenameCommand(dockerCLI command.Cli) *cobra.Command {
	cmd := &cobra.Command{
		Use:   "rename CONTAINER NEW_NAME",
		Short: "Rename a container",
		Args:  cli.ExactArgs(2),
		RunE: func(cmd *cobra.Command, args []string) error {
			oldName, newName := args[0], args[1]
			_, err := dockerCLI.Client().ContainerRename(cmd.Context(), oldName, client.ContainerRenameOptions{
				NewName: newName,
			})
			if err != nil {
				return fmt.Errorf("failed to rename container: %w", err)
			}
			return nil
		},
		Annotations: map[string]string{
			"aliases": "docker container rename, docker rename",
		},
		ValidArgsFunction:     completion.ContainerNames(dockerCLI, true),
		DisableFlagsInUseLine: true,
	}
	return cmd
}

View on GitHub (pinned to 4f84911bfe)