What causes "bad image reference" in slimtoolkit/slim?

Set a valid image reference (name[:tag]) in the service's `image:` field

bad image reference

Error message

bad image reference

What it means

HasImage validates the image reference before checking the Docker daemon: an empty string, '.', or '..' is not a valid image reference, so it returns 'bad image reference' without contacting the daemon. It guards dockerutil.HasImage from receiving a meaningless reference.

Source

Thrown at pkg/app/master/compose/execution.go:1007

			line = strings.TrimSpace(line)
			if len(line) == 0 {
				continue
			}

			if strings.HasPrefix(line, "#") {
				continue
			}

			result = append(result, line)
		}
	}

	return result
}

func HasImage(dclient *dockerapi.Client, imageRef string) (bool, error) {
	if imageRef == "" || imageRef == "." || imageRef == ".." {
		return false, fmt.Errorf("bad image reference")
	}

	info, err := dockerutil.HasImage(dclient, imageRef)
	if err != nil {
		if err == dockerapi.ErrNoSuchImage ||
			err == dockerutil.ErrNotFound {
			return false, nil
		}

		return false, err
	}

	log.Debugf("compose.HasImage(%s): image identity - %#v", imageRef, info)

	var repo string
	var tag string
	if strings.Contains(imageRef, "@") {
		parts := strings.SplitN(imageRef, "@", 2)

View on GitHub (pinned to 81940d17fa)

Solutions

Set a valid image reference (name[:tag]) in the service's `image:` field
Check compose variable interpolation — an env var feeding ${IMAGE} may be unset, producing an empty value
If the service should be built instead, add a `build:` section and enable image building rather than leaving image empty

Example fix

// before (docker-compose.yml)
services:
  api:
    image: ${API_IMAGE}     # API_IMAGE unset -> "" -> bad image reference
// after
services:
  api:
    image: myapp/api:1.0.0

Defensive patterns

Strategy: validation

Validate before calling

func validImageRef(ref string) bool {
    return ref != "" && ref != "." && ref != ".." &&
        strings.ContainsAny(ref, ":/@") || // crude: has tag/registry separator
        regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._/-]*(:[\w.-]+)?$`).MatchString(ref)
}

Try / catch

ok, err := compose.HasImage(cli, img)
if err != nil {
    if strings.Contains(err.Error(), "bad image reference") {
        return fmt.Errorf("image ref %q is empty/invalid, fix compose image field: %w", img, err)
    }
    return err
}

Prevention

Never leave the `image:` key empty or set it to "."/".."
Check env vars used in image interpolation are set (docker compose config)
Use full name:tag references instead of relative-looking paths

When it happens

Trigger: Calling HasImage (e.g. from PrepareService) with service.Image set to "", ".", or ".." — typically when a compose file has an empty or dot-valued image field.

Common situations: A docker-compose.yml with `image: .` or an image key left empty; templating/interpolation that resolved the image variable to empty; passing a relative-path-like value instead of an image reference.

Related errors

AI-assisted analysis of slimtoolkit/slim@81940d17fa (2026-08-31). Data as JSON: /api/errors/b701b65d4116853c. Report an issue: GitHub.