mikefarah/yq · error

can't serialise value because it contains NUL char and you a

Error message

can't serialise value because it contains NUL char and you are using NUL separated output

What it means

When NUL-separated output (`-0`/`--nul-separated-output`) is enabled, yq scans each serialized result for NUL bytes because NUL is the record delimiter. A value containing a NUL character would corrupt the output stream, so printing is aborted with this error.

Source

Thrown at pkg/yqlib/printer.go:134

		var destination io.Writer = writer
		tempBuffer := bytes.NewBuffer(nil)
		if p.nulSepOutput {
			destination = tempBuffer
		}

		if err := p.encoder.PrintLeadingContent(destination, mappedDoc.LeadingContent); err != nil {
			return err
		}

		if err := p.printNode(mappedDoc, destination); err != nil {
			return err
		}

		if p.nulSepOutput {
			removeLastEOL(tempBuffer)
			tempBufferBytes := tempBuffer.Bytes()
			if bytes.IndexByte(tempBufferBytes, 0) != -1 {
				return fmt.Errorf(
					"can't serialise value because it contains NUL char and you are using NUL separated output",
				)
			}
			if _, err := writer.Write(tempBufferBytes); err != nil {
				return err
			}
			if _, err := writer.Write([]byte{0}); err != nil {
				return err
			}
		}

		p.previousDocIndex = mappedDoc.GetDocument()
		if err := writer.Flush(); err != nil {
			return err
		}
		log.Debugf("done printing results")
	}

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Remove or sanitize the NUL character from the data, e.g. `yq '.[] |= gsub("\\u0000"; "")'`
2. Switch to default (newline-separated) output and drop the `-0` flag if NUL-safe piping isn't required
3. Pre-clean the input file (e.g. `tr -d '\0' < input.yaml`) before passing to yq
4. If binary data is expected, base64-encode the field first, e.g. `@base64`

Example fix

// before
yq -0 '.[].blob' file.yaml
// after
yq '.[].blob | @base64' file.yaml

// Check values for NUL bytes before NUL-separated output
if bytes.IndexByte(serialized, 0) != -1 {
	return fmt.Errorf("value contains NUL; cannot use -0 output")
}

func hasNul(s string) bool { return strings.ContainsRune(s, '\x00') }

err := printer.PrintResults(...)
if err != nil && strings.Contains(err.Error(), "NUL char") {
	// sanitize input and retry, or switch to newline-separated output
}

When it happens

Trigger: Outputting results with `-0` where a string value in the document contains an embedded NUL byte (\0), e.g. binary-ish data or a literal null byte in a YAML string.

Common situations: Processing documents with binary blobs or control characters while using NUL separation for shell `xargs -0` pipelines; reading corrupted or binary files misidentified as YAML/JSON.

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