hashicorp/nomad · error · hcl.Diagnostic

Label encoding failed: %v

Error message

Label encoding failed: %v

What it means

ParseHclInterface decodes plugin configuration (an hcl2 body / cty value) into a map. When a labeled block or attribute's value cannot be HCL-encoded, it builds the message "Label encoding failed: %v" with the underlying error and returns it as an hcl.Diagnostic plus an error, e.g. for a label value of the wrong type.

Source

Thrown at helper/pluginutils/hclutils/util.go:47

	evalCtx := &hcl.EvalContext{
		Variables: vars,
		Functions: GetStdlibFuncs(),
	}

	// Encode to json
	var buf bytes.Buffer
	enc := codec.NewEncoder(&buf, structs.JsonHandle)
	err := enc.Encode(val)
	if err != nil {
		// Convert to a hcl diagnostics message
		errorMessage := fmt.Sprintf("Label encoding failed: %v", err)
		return cty.NilVal,
			hcl.Diagnostics([]*hcl.Diagnostic{{
				Severity: hcl.DiagError,
				Summary:  "Failed to encode label value",
				Detail:   errorMessage,
			}}),
			[]error{errors.New(errorMessage)}
	}

	// Parse the json as hcl2
	hclFile, diag := hjson.Parse(buf.Bytes(), "")
	if diag.HasErrors() {
		return cty.NilVal, diag, formattedDiagnosticErrors(diag)
	}

	value, decDiag := hcldec.Decode(hclFile.Body, spec, evalCtx)
	diag = diag.Extend(decDiag)
	if diag.HasErrors() {
		return cty.NilVal, diag, formattedDiagnosticErrors(diag)
	}

	return value, diag, nil
}

// CtyValueToMapInterface converts a decoded cty value into a Go

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the Detail of the returned hcl.Diagnostics — it wraps the underlying encoding error naming the offending label.
2. Fix the job/plugin config so the labeled value matches the expected schema (usually a string label).
3. Validate the config with `nomad job validate` or validatePluginConfig before submitting to catch this client-side.

Example fix

// before (job config)
config {
  image = 42
}
// after
config {
  image = "redis:7"
}

// ensure labeled values are strings before parsing
for k, v := range rawConfig {
    if isLabelKey(k) {
        if _, ok := v.(string); !ok {
            return fmt.Errorf("label %q must be a string, got %T", k, v)
        }
    }
}
_, diags, errs := hclutils.ParseHclInterface(raw, ctyToHclSchema(), nil)

func isStringValue(v interface{}) bool { _, ok := v.(string); return ok }

m, diags, errs := hclutils.ParseHclInterface(in, ctyType, ctx)
if len(errs) > 0 {
    for _, e := range errs {
        if strings.HasPrefix(e.Error(), "Label encoding failed") {
            return fmt.Errorf("check job config label values: %w", e)
        }
    }
    return diags
}

When it happens

Trigger: Calling hclutils.ParseHclInterface (directly or via validatePluginConfig / driver config parsing like runDriver) with a config where a label value cannot be encoded to the expected type — e.g. a non-string value where a string label is required, or malformed nested structures.

Common situations: Task driver plugin config blocks (docker, qemu, etc.) in job files with mistyped values (numbers/booleans where strings are expected); plugin configs loaded via RPC validation; tests feeding cty values of unexpected shape.

Related errors

• failed to parse config:
• error parsing: root should be an object
• invalid key: %s
• failed to convert task schema
• plugin not found

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/21c5ccb93cb78558. Report an issue: GitHub.