Confmap issue with embedded fields and squashed fields

[jmacd]

Component(s)

confmap

What happened?

Describe the bug
Regression in confmap parsing, somehow mysteriously.
This is my config: https://github.com/jmacd/caspar.water/blob/main/storage/influxdbexporter/config.go
This is my build: https://github.com/jmacd/caspar.water/blob/main/collector/build.yaml#L12
It last parsed and validated correctly with a 0.122.0-derived build.

Steps to reproduce
I updated to 0.128.0. I use this configuration block:

exporters:
  influxdb:
    endpoint: "https://casparwater.us:8086"
    org: "casparwater"
    bucket: "production"
    token: "${INFLUXD_TOKEN}"

and this has worked well, until now. Now the validate command prints:

error decoding 'exporters': error reading configuration for "influxdb": decoding failed due to the following error(s):

error decoding '': decoding failed due to the following error(s):

'' has invalid keys: bucket, endpoint, org, token
2025/06/25 23:04:20 collector server run finished with error: failed to get config: cannot unmarshal the configuration: decoding failed due to the following error(s):

error decoding 'exporters': error reading configuration for "influxdb": decoding failed due to the following error(s):

error decoding '': decoding failed due to the following error(s):

'' has invalid keys: bucket, endpoint, org, token

What did you expect to see?
This is a regression of some sort. The config used to validate.

What did you see instead?
The error above.

Collector version

v0.128.0

Environment information

Environment

go-1.23.2
darwin/arm64

OpenTelemetry Collector configuration

Linked in the text

Log output

See above.

Additional context

No response

[github-actions]

Pinging code owners:

• confmap: @mx-psi @evan-bradley

See Adding Labels via Comments if you do not have permissions to add labels yourself.

[jmacd]

I know this code base very well, but it's still a super-mysterious error. Is there any way to print the type of the mysterious object '' has invalid keys: bucket, endpoint, org, token, or maybe print which keys are valid? This is a very discouraging message to receive, especially considering that all I did was upgrade versions,.

[mx-psi]

@jmacd Could you try to bisect this? It would also be helpful to get a full configuration file (or set of files) that reproduces this. I can take a look next week when I am fully back

[VihasMakwana]

This error can only occur if there is a field in config yaml which isn't present in struct. I tried validate subcommand couple of times with upstream components and it passed.
If I specify an absent field, I get a similar error as yours.

[jmacd]

I will bisect. After we figure it out, I will advocate for a more-helpful error message. 😁

[VihasMakwana]

@jmacd I would also give this a shot.

I will advocate for a more-helpful error message

yeah, the error originates from mapstructure library we use. We need better error

[jmacd]

I had an extremely hard time trying to build older versions what with the way go get works. I couldn't get any version but the latest to build for my multi-component-repo setup. I was able to determine that by commenting out the

	//exporterhelper.QueueConfig `mapstructure:"sending_queue"`

field (which I wasn't using), the problem went away.

I traced this in a very hacky way and observed that the QueueConfig object was trying to parse the InfluxDB fields. I think an isolated example will help.

[jmacd]

Part of #13278

[jmacd]

Root Cause Identified: The error occurs due to an issue with how the collector handles embedded structs with squash tags when ErrorUnused=true is enabled in mapstructure.

What's Happening:

The exporter config is:

type Config struct {
	confighttp.ClientConfig      `mapstructure:",squash"`
	exporterhelper.QueueConfig `mapstructure:"sending_queue"`
	configretry.BackOffConfig    `mapstructure:"retry_on_failure"`

	Org string `mapstructure:"org"`
	Bucket string `mapstructure:"bucket"`
	Token configopaque.String `mapstructure:"token"`
}

The yaml was:

exporters:
  influxdb:
    endpoint: "https://casparwater.us:8086"
    org: "casparwater"
    bucket: "production"
    token: "${INFLUXD_TOKEN}"

When validating, the entire exporter config (including endpoint, org, bucket, token) gets passed to QueueConfig.Unmarshal()
Since QueueConfig only recognizes queue-related fields, it reports the InfluxDB-specific fields as "invalid keys"
The unhelpful error message '' has invalid keys: ... occurs because the struct name is empty in this context

Technical Details:

Error originates in go-viper/mapstructure/v2 library's decodeStructFromMap function
This is an incompatibility between ErrorUnused validation and squashed embedded structs

Long-term Solutions:

mapstructure: Improve error messages to show struct type when name is empty
OpenTelemetry Collector: Modify architecture to pass only relevant config subsets to embedded struct unmarshalers, avoiding the ErrorUnused + squash conflict
This investigation reveals a broader architectural issue affecting projects using similar embedded struct patterns with strict config validation. RECOMMENDATION: Do not mix embedded structs with the use of squash!

[mx-psi]

This investigation reveals a broader architectural issue affecting projects using similar embedded struct patterns with strict config validation

I am curious if we see this pattern elsewhere