mikefarah/yq · error

failed to encode HCL: %w

Error message

failed to encode HCL: %w

What it means

Wrapper error for the HCL encoder: any failure while converting the CandidateNode tree into HCL body content is wrapped with 'failed to encode HCL'. The underlying cause (unsupported node shape, bad raw expression, non-mapping root, etc.) is chained via %w.

Source

Thrown at pkg/yqlib/encoder_hcl.go:58

func (he *hclEncoder) PrintLeadingContent(_ io.Writer, _ string) error {
	return nil
}

func (he *hclEncoder) Encode(writer io.Writer, node *CandidateNode) error {
	log.Debugf("I need to encode %v", NodeToString(node))
	if node.Kind == ScalarNode {
		return writeString(writer, node.Value+"\n")
	}

	f := hclwrite.NewEmptyFile()
	body := f.Body()

	// Collect comments as we encode
	commentMap := make(map[string]string)
	he.collectComments(node, "", commentMap)

	if err := he.encodeNode(body, node); err != nil {
		return fmt.Errorf("failed to encode HCL: %w", err)
	}

	// Get the formatted output and remove extra spacing before '='
	output := f.Bytes()
	compactOutput := he.compactSpacing(output)

	// Inject comments back into the output
	finalOutput := he.injectComments(compactOutput, commentMap)

	if he.prefs.ColorsEnabled {
		colourized := he.colorizeHcl(finalOutput)
		_, err := writer.Write(colourized)
		return err
	}

	_, err := writer.Write(finalOutput)
	return err
}

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Read the wrapped cause below this message to identify the real failure
2. Reshape the input so the root is a mapping of HCL-representable values
3. Remove aliases (or resolve them) before encoding: `yq '... alias-resolving expr ...' -o hcl`
4. Validate the data structure against HCL block expectations before encoding

Example fix

// before: yq -o hcl '.' malformed.yaml
// after:  yq -o hcl '( ... | del(.alias_field) )' input.yaml  — fix the underlying cause first

// pre-validate with yq before encoding to HCL:
// yq 'type == "!!map" and ([.. | tag] | any("!!alias" | not))' input.yaml

if err := he.Encode(writer, node); err != nil {
    var wrapped = fmt.Errorf("hcl encode failed: %w", err)
    log.Printf("%v", wrapped) // inspect chained cause for the real error
    return fallbackFormat(node) // e.g. emit JSON instead
}

When it happens

Trigger: Running `yq -o hcl` on data the HCL encoder cannot represent — e.g. a root that is not a mapping, a node with an alias, or an attribute value whose raw expression contains unsupported characters.

Common situations: Converting YAML/JSON config to HCL/Terraform where the data contains constructs HCL cannot express (aliases, deeply nested non-block shapes); inspect the chained cause with `%+v` or stderr detail.

Related errors

• unsupported character %q in raw HCL expression
• HCL encoder expects a mapping at the root level, got %v
• expected mapping node for block body
• HCL encoder does not support aliases
• unsupported node kind: %v

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