What causes "unknown instruction" in slimtoolkit/slim?

Fix the instruction spelling to a valid Dockerfile keyword (RUN, COPY, ENV, etc.)

unknown instruction

Error message

unknown instruction

What it means

ErrDockerfileUnknownInst is the sentinel error for unrecognized Dockerfile instructions; its message is the constant UnknownInstMsg ('unknown instruction'). The AST parser's dispatch table maps known instruction keywords to line parsers, and any keyword not in the table produces this error (often wrapped in a ParseError with the offending line).

Source

Thrown at pkg/docker/dockerfile/ast/parser.go:25

	"bufio"
	"bytes"
	"fmt"
	"io"
	"regexp"
	"strconv"
	"strings"
	"unicode"

	"github.com/pkg/errors"
	"github.com/slimtoolkit/slim/pkg/docker/instruction"
)

const (
	UnknownInstMsg = "unknown instruction"
)

var (
	ErrDockerfileUnknownInst = errors.New(UnknownInstMsg)
)

type ParseError struct {
	Context string
	Data    string
	Message string
}

func (e ParseError) Error() string {
	return e.Message
}

func pe(context, data, message string) ParseError {
	return ParseError{
		Context: context,
		Data:    data,
		Message: message,
	}

View on GitHub (pinned to 81940d17fa)

Solutions

Fix the instruction spelling to a valid Dockerfile keyword (RUN, COPY, ENV, etc.)
Remove or comment out the unsupported line
Upgrade the parser/tooling if the instruction is valid in newer Docker/BuildKit versions
Check for lines accidentally pasted that are not Dockerfile instructions

Example fix

# before
RUNN apt-get update
# after
RUN apt-get update

Defensive patterns

Strategy: type-guard

Validate before calling

// Go: validate instruction keywords against the known set before parsing
var known = map[string]bool{"RUN": true, "CMD": true, "COPY": true, "FROM": true /* ... */}
if !known[strings.ToUpper(keyword)] {
    return fmt.Errorf("unsupported instruction: %s", keyword)
}

Type guard

func IsUnknownInstruction(err error) bool {
    return errors.Is(err, ast.ErrDockerfileUnknownInst) ||
        strings.Contains(err.Error(), ast.UnknownInstMsg)
}

Try / catch

res, err := ast.Parse(dockerfile)
if err != nil {
    if errors.Is(err, ast.ErrDockerfileUnknownInst) {
        // report the offending line/context from ParseError
    }
    return err
}

Prevention

Spell-check Dockerfile instructions; run hadolint or the built-in linter in CI
Watch for non-Dockerfile lines accidentally pasted into the file
Keep the slim parser updated for new Docker/BuildKit instructions

When it happens

Trigger: Parsing a Dockerfile containing a misspelled or unsupported instruction (e.g., RUNN, INSTAL); using an instruction from a newer/other builder (BuildKit-only syntax like heredoc headers) with this parser; custom instructions the slim linter doesn't know.

Common situations: Typos in Dockerfile keywords; copy-pasting syntax from other tools (CI yaml, shell scripts pasted into the Dockerfile); parser not updated for new Docker instructions.

Related errors

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