What causes "could not load %s" in mikefarah/yq?

Use a full yq build that includes the needed format decoder

could not load %s

Error message

could not load %s

What it means

The `load` operators (load, load_yaml, load_json, etc.) resolve a file path at evaluation time. loadWithDecoder first checks that a decoder factory exists for the requested format; if none is registered (e.g. a stripped yq build compiled without that format via build tags), it cannot proceed and reports 'could not load <file>'. This surfaces as a load failure even though the file may exist.

Source

Thrown at pkg/yqlib/operator_load.go:35

type loadPrefs struct {
	decoder Decoder
}

func loadString(filename string) (*CandidateNode, error) {
	// ignore CWE-22 gosec issue - that's more targeted for http based apps that run in a public directory,
	// and ensuring that it's not possible to give a path to a file outside that directory.

	filebytes, err := os.ReadFile(filename) // #nosec
	if err != nil {
		return nil, err
	}

	return &CandidateNode{Kind: ScalarNode, Tag: "!!str", Value: string(filebytes)}, nil
}

func loadWithDecoder(filename string, decoder Decoder) (*CandidateNode, error) {
	if decoder == nil {
		return nil, fmt.Errorf("could not load %s", filename)
	}

	file, err := os.Open(filename) // #nosec
	if err != nil {
		return nil, err
	}
	reader := bufio.NewReader(file)

	documents, err := readDocuments(reader, filename, 0, decoder)
	if err != nil {
		return nil, err
	}

	if documents.Len() == 0 {
		// return null candidate
		return &CandidateNode{Kind: ScalarNode, Tag: "!!null"}, nil
	} else if documents.Len() == 1 {
		candidate := documents.Front().Value.(*CandidateNode)

View on GitHub (pinned to 8b5af0694b)

Solutions

Use a full yq build that includes the needed format decoder
Check the binary's supported formats (yq --help) and pick the matching load operator
Pre-convert the file with a tool that supports the format, then load it as yaml/json
If building yq yourself, remove the yq_no<format> build tag for the required format

Example fix

// before (yq built with -tags yq_noxml)
yq '.a = load_xml("data.xml")' doc.yaml
// error: could not load data.xml

// after: use a full build, or load a supported format
yq '.a = load("data.yaml")' doc.yaml

Defensive patterns

Strategy: fallback

Validate before calling

test -f data.xml && yq --help | grep -q xml && echo "format supported"

Try / catch

out=$(yq '.a = load_xml("data.xml")' doc.yaml 2>&1) || {
  echo "load failed (decoder unavailable or file missing): $out" >&2
  exit 1
}

Prevention

Pin the full yq distribution in CI images
Verify the binary supports the format before using load_<format>
Check file existence with test -f before load expressions
Convert exotic formats to yaml/json upstream

When it happens

Trigger: Using `load_xml("f.xml")` (or another format-specific loader) with a yq binary compiled without that format (yq_noxml-style build tags), so the decoder factory returns nil.

Common situations: Minimal/small yq distributions (tinygo, stripped builds) missing optional formats; mixing up operator names so an unavailable loader is invoked; custom builds where format registration was omitted.

Related errors

AI-assisted analysis of mikefarah/yq@8b5af0694b (2026-09-05). Data as JSON: /api/errors/70580944802e19f3. Report an issue: GitHub.