slimtoolkit/slim · error

invalid dockerfile reference - %s

Error message

invalid dockerfile reference - %s

What it means

NewBasicImageBuilder returns 'invalid dockerfile reference - %s' when the Dockerfile path computed inside the build context does not exist or is not a regular file. The builder joins the context directory with the Dockerfile name and validates it before building. This catches a broken Dockerfile reference before invoking a Docker build.

Source

Thrown at pkg/app/master/builder/image_builder.go:117

			Target:         cbOpts.Target,
			NetworkMode:    cbOpts.NetworkMode,
			ExtraHosts:     cbOpts.ExtraHosts,
			CacheFrom:      cbOpts.CacheFrom,
			Labels:         labels,
			BuildArgs:      buildArgs,
			RmTmpContainer: true,
		},
		APIClient: client,
	}

	if strings.HasPrefix(buildContext, "http://") || strings.HasPrefix(buildContext, "https://") {
		builder.BuildOptions.Remote = buildContext
	} else {
		if exists := fsutil.DirExists(buildContext); exists {
			builder.BuildOptions.ContextDir = buildContext
			fullDockerfileName := filepath.Join(buildContext, cbOpts.Dockerfile)
			if !fsutil.Exists(fullDockerfileName) || !fsutil.IsRegularFile(fullDockerfileName) {
				return nil, fmt.Errorf("invalid dockerfile reference - %s", fullDockerfileName)
			}
		} else {
			return nil, ErrInvalidContextDir
		}
	}

	builder.BuildOptions.OutputStream = &builder.BuildLog
	return &builder, nil
}

// Build creates a new container image
func (b *BasicImageBuilder) Build() error {
	return b.APIClient.BuildImage(b.BuildOptions)
}

// Remove deletes the configured container image
func (b *BasicImageBuilder) Remove() error {
	return nil

View on GitHub (pinned to 81940d17fa)

Solutions

1. Verify the file exists: ls <buildContext>/<Dockerfile>; fix the context dir or Dockerfile name option.
2. Ensure the Dockerfile is inside the build context (or copy it in before building).
3. Check the path is a regular file, not a directory or dangling symlink.
4. If a custom name is used, confirm the exact casing matches the on-disk filename.

Example fix

// before
builder, err := NewBasicImageBuilder(ctx, client, "./ctx", cbOpts) // cbOpts.Dockerfile = "dockerfile.prod" (missing)
// after
cbOpts.Dockerfile = "Dockerfile.prod" // must exist inside ./ctx
builder, err := NewBasicImageBuilder(ctx, client, "./ctx", cbOpts)

full := filepath.Join(buildContext, cbOpts.Dockerfile)
info, err := os.Stat(full)
if err != nil || !info.Mode().IsRegular() {
    return fmt.Errorf("dockerfile %s missing or not a regular file", full)
}

builder, err := NewBasicImageBuilder(ctx, client, ctxDir, cbOpts)
if err != nil {
    if strings.Contains(err.Error(), "invalid dockerfile reference") {
        return fmt.Errorf("check -c and --dockerfile: %w", err)
    }
    return err
}

When it happens

Trigger: NewBasicImageBuilder called with a buildContext directory that lacks cbOpts.Dockerfile, or where that path is a directory/symlink-to-nothing; buildContext exists but points to the wrong directory.

Common situations: Passing a custom --dockerfile-name that does not exist in the context; Dockerfile stored outside the context dir; case-sensitivity mismatch on Linux; context path pointing at an empty staging directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• when using JSON array syntax, arrays must be comprised of st
• unknown instruction
• only one escape parser directive can be used
• invalid Dockerfile
• bad instruction prefix

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