docker/cli · error

invalid stack name

Error message

invalid stack name: %q

What it means

Raised by validateStackName when the provided stack name (namespace) is empty after trimming leading/trailing whitespace and quote characters. The stack name is used as a label namespace (com.docker.stack.namespace) to scope all stack resources, so an empty value would make resource lookup impossible.

Solutions

1. Provide a non-empty stack name consisting of real characters, e.g. `docker stack deploy mystack -c compose.yml`.
2. Check the shell variable feeding the command: `${STACK_NAME:?STACK_NAME must be set}`.
3. Validate the name programmatically before calling the CLI (see validationCode).
4. Avoid wrapping the argument in extra quotes that survive into the arg.

Example fix

// before
STACK_NAME=""
docker stack deploy "$STACK_NAME" -c compose.yml
// after
STACK_NAME="mystack"
docker stack deploy "$STACK_NAME" -c compose.yml

// Validate a stack name before invoking the CLI
import (
    "strings"
    "unicode"
)

func isValidStackName(name string) bool {
    trim := func(r rune) rune {
        if unicode.IsSpace(r) || r == '"' || r == '\'' {
            return -1
        }
        return r
    }
    return strings.Map(trim, name) != ""
}

type StackName string

func (s StackName) Validate() error {
    if strings.TrimSpace(strings.Trim(string(s), `"'`)) == "" {
        return errors.New("empty stack name")
    }
    return nil
}

When it happens

Trigger: Invoking `docker stack <cmd> ""` or `docker stack <cmd> ' '` or `docker stack <cmd> '""'` (a value that is empty after stripping spaces and quotes). validateStackName is called from ps.go, remove.go, deploy.go, and other stack subcommands before any API call.

Common situations: A shell variable that resolved to empty (e.g. $STACK_NAME unset) passed as the stack argument; quoting bugs where literal quotes become part of the argument; CI templates that interpolate an empty variable.

Related errors

• specify a Compose file (with --compose-file)
• compose file contains unsupported options
• invalid image reference for service
• invalid image reference for service
• unexpected environment variable

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

Appendix: source

Thrown at cli/command/stack/common.go:20

import (
	"context"
	"fmt"
	"strings"
	"unicode"

	"github.com/docker/cli/cli/compose/convert"
	"github.com/docker/cli/opts"
	"github.com/moby/moby/client"
)

// validateStackName checks if the provided string is a valid stack name (namespace).
// It currently only does a rudimentary check if the string is empty, or consists
// of only whitespace and quoting characters.
func validateStackName(namespace string) error {
	v := strings.TrimFunc(namespace, quotesOrWhitespace)
	if v == "" {
		return fmt.Errorf("invalid stack name: %q", namespace)
	}
	return nil
}

func validateStackNames(namespaces []string) error {
	for _, ns := range namespaces {
		if err := validateStackName(ns); err != nil {
			return err
		}
	}
	return nil
}

func quotesOrWhitespace(r rune) bool {
	return unicode.IsSpace(r) || r == '"' || r == '\''
}

func getStackFilter(namespace string) client.Filters {

View on GitHub (pinned to 4f84911bfe)