mikefarah/yq · error

HCL encoder does not support aliases

Error message

HCL encoder does not support aliases

What it means

nodeToCtyValue hit an AliasNode while converting the CandidateNode tree to a cty value for HCL emission. The HCL encoder cannot resolve YAML anchors/aliases (cty values are concrete), so any alias remaining in the tree — because the encoder's CanHandleAliases is false and the node was not exploded first — aborts conversion with this sentinel-style guard error.

Source

Thrown at pkg/yqlib/encoder_hcl.go:686

			v, err := nodeToCtyValue(valueNode)
			if err != nil {
				return cty.NilVal, err
			}
			m[keyNode.Value] = v
		}
		return cty.ObjectVal(m), nil
	case SequenceNode:
		vals := make([]cty.Value, len(node.Content))
		for i, item := range node.Content {
			v, err := nodeToCtyValue(item)
			if err != nil {
				return cty.NilVal, err
			}
			vals[i] = v
		}
		return cty.TupleVal(vals), nil
	case AliasNode:
		return cty.NilVal, fmt.Errorf("HCL encoder does not support aliases")
	default:
		return cty.NilVal, fmt.Errorf("unsupported node kind: %v", node.Kind)
	}
}

View on GitHub (pinned to 8b5af0694b)

Solutions

1. Resolve aliases before encoding, e.g. pipe through a tool/expression that dereferences anchors (yq evaluation typically resolves aliases on traversal; ensure the value is a real node)
2. Manually expand the anchor into a full mapping in the input
3. Use `-o json` intermediate step: `yq -o json | yq -o hcl` to materialize the data

Example fix

// before: derived: *b   (alias)
// after:  derived: {a: 1}  (expanded mapping)

yq '[.. | tag] | any("!!alias")' input.yaml   # must print false before -o hcl

func containsAlias(node *CandidateNode) bool {
  if node.Kind == AliasNode { return true }
  for _, c := range node.Content {
    if containsAlias(c) { return true }
  }
  return false
}

v, err := nodeToCtyValue(node)
if err != nil && strings.Contains(err.Error(), "does not support aliases") {
    // dereference/expand the alias, then retry the encode
}

When it happens

Trigger: `yq -o hcl` on YAML input containing anchors/aliases, e.g. `base: &b {a: 1}` then `derived: *b` — encoding the derived field hits the AliasNode case.

Common situations: Terraform module configs written with YAML anchors to deduplicate blocks; users converting anchor-heavy YAML to HCL for Terraform.

Related errors

• failed to encode HCL: %w
• unsupported character %q in raw HCL expression
• HCL encoder expects a mapping at the root level, got %v
• expected mapping node for block body
• unsupported node kind: %v

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