What causes "not found" in slimtoolkit/slim?

Run 'docker images' / 'docker volume ls' to confirm the referenced image or volume exists.

not found

Error message

not found

What it means

ErrNotFound is a sentinel error from dockerutil indicating the requested Docker resource does not exist. It is returned by DoArchiveState, NoImage, HasImage, HasVolume, and WithDefaultConfigPath when the referenced image, volume, file, or default config path cannot be located. Unlike ErrBadParam it means the input was valid but the target is absent.

Source

Thrown at pkg/docker/dockerutil/dockerutil.go:25

	"errors"
	"fmt"
	"io"
	"os"
	"path/filepath"
	"strings"
	"time"

	"github.com/docker/docker/pkg/archive"
	dockerapi "github.com/fsouza/go-dockerclient"
	log "github.com/sirupsen/logrus"

	"github.com/slimtoolkit/slim/pkg/docker/dockerclient"
	"github.com/slimtoolkit/slim/pkg/util/fsutil"
)

var (
	ErrBadParam = errors.New("bad parameter")
	ErrNotFound = errors.New("not found")
)

const (
	volumeMountPat       = "%s:/data"
	volumeBasePath       = "/data"
	emptyImageName       = "docker-slim-empty-image:latest"
	emptyImageDockerfile = "FROM scratch\nCMD\n"
)

type BasicImageProps struct {
	ID      string
	Size    int64
	Created int64
}

type ImageIdentity struct {
	ID           string
	ShortTags    []string

View on GitHub (pinned to 81940d17fa)

Solutions

Run 'docker images' / 'docker volume ls' to confirm the referenced image or volume exists.
Pull or build the image (or create the volume) before invoking the function.
Verify the exact name:tag including registry prefix matches what Docker reports.
For WithDefaultConfigPath, create the config directory or point the tool at an explicit path.

Example fix

// before
if err := dockerutil.HasVolume(ctx, client, "myvol"); err != nil { ... } // volume missing
// after
if _, err := client.CreateVolume(docker.CreateVolumeOptions{Name: "myvol"}); err != nil && err.Error() != "volume exists" {
    return err
}
exists, err := dockerutil.HasVolume(ctx, client, "myvol")

Defensive patterns

Strategy: try-catch

Validate before calling

images, _ := client.ListImages(docker.ListImagesOptions{All: true})
found := false
for _, img := range images {
    for _, tag := range img.RepoTags {
        if tag == imageName { found = true }
    }
}
if !found { /* pull or build first */ }

Try / catch

exists, err := dockerutil.HasImage(ctx, client, imageName)
switch {
case errors.Is(err, dockerutil.ErrNotFound):
    // auto-pull or report 'image not found: <name>'
case err != nil:
    return err
}

Prevention

Check docker images / docker volume ls before referencing a resource.
Use fully qualified name:tag including registry prefix.
Create volumes/config paths during environment setup scripts.
Distinguish ErrNotFound from ErrBadParam in error handling.

When it happens

Trigger: HasImage/NoImage with an image name not present locally; HasVolume for a nonexistent volume; DoArchiveState on a missing path in a container; WithDefaultConfigPath when the default config directory does not exist.

Common situations: Image built under a different tag than the one referenced; volume removed between runs or on a different Docker host; running inside a container where default config paths are not mounted; typo'd image name or registry prefix.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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