What causes "malformed change data hash matcher: %s" in slimtoolkit/slim?

Use the 3-field form: dump: : , e.g. dump:/tmp/out:sha256:... becomes problematic — prefer dump::'d41d8...' with an empty output field if the hash itself contains no colons.

slimtoolkit/slim · error

malformed change data hash matcher: %s

Error message

malformed change data hash matcher: %s

What it means

parseChangeDataHashMatchers in the xray command (pkg/app/master/command/xray/cli.go:525) parses --change-data-hash values. A value starting with 'dump:' must have the 3-part form 'dump:output:hash' (SplitN on ':' into exactly 3 parts); shorter values like 'dump:console' or 'dump:/tmp/hashes' return "malformed change data hash matcher: %s".

Source

Thrown at pkg/app/master/command/xray/cli.go:525

			}
		}

		matchers = append(matchers, &m)
	}

	return matchers, nil
}

func parseChangeDataHashMatchers(values []string) ([]*dockerimage.ChangeDataHashMatcher, error) {
	var matchers []*dockerimage.ChangeDataHashMatcher

	for _, raw := range values {
		var m dockerimage.ChangeDataHashMatcher

		if strings.HasPrefix(raw, "dump:") {
			parts := strings.SplitN(raw, ":", 3)
			if len(parts) != 3 {
				return nil, fmt.Errorf("malformed change data hash matcher: %s", raw)
			}

			m.Dump = true

			outTarget := strings.TrimSpace(parts[1])
			if len(outTarget) == 0 || outTarget == dockerimage.CDMDumpToConsole {
				m.DumpConsole = true
			} else {
				m.DumpDir = outTarget
			}

			m.Hash = strings.ToLower(strings.TrimSpace(parts[2]))

			//"dump:output:hash"
			//"::hash"
			//"hash"
		} else {
			if !strings.HasPrefix(raw, ":") {

View on GitHub (pinned to 81940d17fa)

Solutions

Use the 3-field form: dump:<output-dir-or-empty>:<hash>, e.g. dump:/tmp/out:sha256:... becomes problematic — prefer dump::'d41d8...' with an empty output field if the hash itself contains no colons.
If your hash contains colons (e.g. 'sha256:abc...'), note SplitN's 3-part limit keeps the remainder in the last field, so 'dump:/tmp/out:sha256:abc' still works — the missing-field case is what fails.
Without dumping, pass just the hash string, e.g. --change-data-hash 'd41d8cd98f00b204e9800998ecf8427e'.
Count separators: a 'dump:'-prefixed hash matcher needs at least 2 colons.

Example fix

// before
--change-data-hash 'dump:/tmp/out'
// after
--change-data-hash 'dump:/tmp/out:d41d8cd98f00b204e9800998ecf8427e'

Defensive patterns

Strategy: validation

Validate before calling

// validate a dump-form change-data-hash matcher before invoking the CLI
func validDumpHashMatcher(raw string) bool {
    if !strings.HasPrefix(raw, "dump:") {
        return true
    }
    return len(strings.SplitN(raw, ":", 3)) == 3
}

Try / catch

matchers, err := parseChangeDataHashMatchers(values)
if err != nil {
    if strings.HasPrefix(err.Error(), "malformed change data hash matcher") {
        fmt.Fprintf(os.Stderr, "expected dump:out:hash (2+ colons): %v\n", err)
        os.Exit(2)
    }
    return err
}

Prevention

Hash matcher dump form = 3 fields: dump:out:hash — always include the hash.
Algorithms prefixes like 'sha256:abc...' are fine; the last field absorbs extra colons (SplitN limit 3).
Without dumping, pass just the hex hash string.
Store hashes in variables to avoid hand-built strings with missing fields.

When it happens

Trigger: Passing a --change-data-hash value beginning with 'dump:' with only 2 colon-separated fields — e.g. 'dump:console' or 'dump:/tmp/dump' — omitting the hash field.

Common situations: Stopping after the dump target and forgetting the hash; pasting data-matcher dump syntax (4 fields) or path-matcher dump syntax without the final field; documentation examples truncated.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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