Fix ExpandedValue sanitization on struct collection

confmap/internal/decoder.go

@@ -93,14 +93,26 @@ func useExpandValue() mapstructure.DecodeHookFuncType {
 			return v, nil
 		}
 
-		switch to.Kind() {
-		case reflect.Array, reflect.Slice, reflect.Map:
-			if isStringyStructure(to) {
-				// If the target field is a stringy structure, sanitize to use the original string value everywhere.
-				return sanitizeToStr(data), nil
+		if !DeferExpandedValueSanitizationOnStructCollection.IsEnabled() {
+			switch to.Kind() {
+			case reflect.Array, reflect.Slice:
+				elemType := to.Elem()
+				// If the element type is a struct, don't sanitize at the collection level.
+				// Let mapstructure decode field-by-field so each ExpandedValue can be
+				// converted based on its target field type.
+				if elemType.Kind() == reflect.Struct {
+					return data, nil
+				}
+				fallthrough
+
+			case reflect.Map:
+				if isStringyStructure(to) {
+					// If the target field is a stringy structure, sanitize to use the original string value everywhere.
+					return sanitizeToStr(data), nil
+				}
+				// Otherwise, sanitize to use the parsed value everywhere.
+				return sanitize(data), nil
 			}
-			// Otherwise, sanitize to use the parsed value everywhere.
-			return sanitize(data), nil
 		}
 		return data, nil
 	}

confmap/internal/e2e/maplist_expanded_test.go

@@ -0,0 +1,92 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package e2etest
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"go.opentelemetry.io/collector/config/configopaque"
+	"go.opentelemetry.io/collector/confmap"
+	"go.opentelemetry.io/collector/confmap/internal"
+)
+
+type testHeadersConfig struct {
+	Headers configopaque.MapList `mapstructure:"headers"`
+}
+
+// TestMapListWithExpandedValue tests that MapList can handle ExpandedValue
+// from environment variable expansion
+func TestMapListWithExpandedValue(t *testing.T) {
+	// Simulate what happens when ${env:TOKEN} is expanded
+	// The confmap will contain an ExpandedValue instead of a plain string
+	data := map[string]any{
+		"headers": []any{
+			map[string]any{
+				"name": "Authorization",
+				"value": internal.ExpandedValue{
+					Value:    "Bearer secret-token",
+					Original: "Bearer secret-token",
+				},
+			},
+		},
+	}
+
+	conf := confmap.NewFromStringMap(data)
+	var tc testHeadersConfig
+	err := conf.Unmarshal(&tc)
+	require.NoError(t, err)
+
+	val, ok := tc.Headers.Get("Authorization")
+	require.True(t, ok)
+	require.Equal(t, configopaque.String("Bearer secret-token"), val)
+}
+
+// TestMapListWithExpandedValueIntValue tests an ExpandedValue with an integer Value
+func TestMapListWithExpandedValueIntValue(t *testing.T) {
+	// Simulate what happens when expanding a value that parses as an int
+	data := map[string]any{
+		"headers": []any{
+			map[string]any{
+				"name": "X-Port",
+				"value": internal.ExpandedValue{
+					Value:    8080,   // Value is parsed as int
+					Original: "8080", // Original is string
+				},
+			},
+		},
+	}
+
+	conf := confmap.NewFromStringMap(data)
+	var tc testHeadersConfig
+	err := conf.Unmarshal(&tc)
+	require.NoError(t, err)
+
+	val, ok := tc.Headers.Get("X-Port")
+	require.True(t, ok)
+	require.Equal(t, configopaque.String("8080"), val)
+}
+
+// TestDirectConfigopaqueStringWithExpandedValueIntValue tests that direct unmarshaling works
+func TestDirectConfigopaqueStringWithExpandedValueIntValue(t *testing.T) {
+	type testConfig struct {
+		Value configopaque.String `mapstructure:"value"`
+	}
+
+	// Direct configopaque.String field (not in a map/slice structure)
+	data := map[string]any{
+		"value": internal.ExpandedValue{
+			Value:    8080,
+			Original: "8080",
+		},
+	}
+
+	conf := confmap.NewFromStringMap(data)
+	var tc testConfig
+	err := conf.Unmarshal(&tc)
+	// This should work because useExpandValue detects the target is a string
+	require.NoError(t, err)
+	require.Equal(t, configopaque.String("8080"), tc.Value)
+}

confmap/internal/featuregates.go

@@ -12,3 +12,11 @@ var EnableMergeAppendOption = featuregate.GlobalRegistry().MustRegister(
 	featuregate.WithRegisterDescription("Combines lists when resolving configs from different sources. This feature gate will not be stabilized 'as is'; the current behavior will remain the default."),
 	featuregate.WithRegisterReferenceURL("https://github.com/open-telemetry/opentelemetry-collector/issues/8754"),
 )
+
+var DeferExpandedValueSanitizationOnStructCollection = featuregate.GlobalRegistry().MustRegister(
+	"confmap.deferExpandedValueSanitizationOnStructCollection",
+	featuregate.StageBeta,
+	featuregate.WithRegisterFromVersion("v0.144.0"),
+	featuregate.WithRegisterDescription("Disables early sanitization of ExpandedValue during config unmarshalling, allowing mapstructure to handle type conversion at the field level. Fixes decoding errors when environment variable values are parsed as non-string types (e.g., numbers, booleans) but need to be assigned to string fields."),
+	featuregate.WithRegisterReferenceURL("https://github.com/open-telemetry/opentelemetry-collector/pull/14413#issuecomment-3754949484"),
+)