hyperledger/fabric · error

invalid external builder configuration, path attribute missi

Error message

invalid external builder configuration, path attribute missing in one or more builders

What it means

During peer config load, every entry in externalBuilders must have a non-empty path attribute; if any builder omits it, load() aborts peer startup with this error. The path tells the peer where the builder's binary lives on disk, so a missing path makes the builder unusable. It is a static YAML validation error surfaced at boot.

Source

Thrown at core/peer/config.go:304

	c.VMDockerAttachStdout = viper.GetBool("vm.docker.attachStdout")

	c.VMNetworkMode = viper.GetString("vm.docker.hostConfig.NetworkMode")
	if c.VMNetworkMode == "" {
		c.VMNetworkMode = "host"
	}

	c.ChaincodePull = viper.GetBool("chaincode.pull")
	var externalBuilders []ExternalBuilder

	err = viper.UnmarshalKey("chaincode.externalBuilders", &externalBuilders, viper.DecodeHook(viperutil.YamlStringToStructHook(externalBuilders)))
	if err != nil {
		return err
	}

	c.ExternalBuilders = externalBuilders
	for builderIndex, builder := range c.ExternalBuilders {
		if builder.Path == "" {
			return errors.New("invalid external builder configuration, path attribute missing in one or more builders")
		}
		if builder.Name == "" {
			return fmt.Errorf("external builder at path %s has no name attribute", builder.Path)
		}
		if builder.Environment != nil && len(builder.PropagateEnvironment) == 0 {
			c.ExternalBuilders[builderIndex].PropagateEnvironment = builder.Environment
		}
	}

	c.OperationsListenAddress = viper.GetString("operations.listenAddress")
	c.OperationsTLSEnabled = viper.GetBool("operations.tls.enabled")
	c.OperationsTLSCertFile = config.GetPath("operations.tls.cert.file")
	c.OperationsTLSKeyFile = config.GetPath("operations.tls.key.file")
	c.OperationsTLSClientAuthRequired = viper.GetBool("operations.tls.clientAuthRequired")

	for _, rca := range viper.GetStringSlice("operations.tls.clientRootCAs.files") {
		c.OperationsTLSClientRootCAs = append(c.OperationsTLSClientRootCAs, config.TranslatePath(configDir, rca))
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Add the missing path key to every externalBuilders entry in core.yaml (or the mounted config) and restart the peer.
2. Validate the rendered YAML before deployment: ensure each builder has both path and name set.
3. If the path comes from a template variable, fix the variable so it resolves to the builder's directory (e.g. /builders/ccaas_builder).
4. Temporarily remove the incomplete builder entry if it is not needed, then start the peer.

Example fix

# before
externalBuilders:
  - name: ccaas-builder
    propagateEnvironment:
      - FABRIC_VERSION
# after
externalBuilders:
  - name: ccaas-builder
    path: /builders/ccaas_builder
    propagateEnvironment:
      - FABRIC_VERSION

import "gopkg.in/yaml.v2"
var cfg struct {
    ExternalBuilders []struct {
        Name string `yaml:"name"`
        Path string `yaml:"path"`
    } `yaml:"externalBuilders"`
}
if err := yaml.Unmarshal(coreYAML, &cfg); err != nil { return err }
for i, b := range cfg.ExternalBuilders {
    if b.Path == "" {
        return fmt.Errorf("externalBuilders[%d] (%s) missing path", i, b.Name)
    }
}

if err := peer.Config(); err != nil {
    if strings.Contains(err.Error(), "path attribute missing") {
        return fmt.Errorf("fix core.yaml externalBuilders: %w", err)
    }
    return err
}

When it happens

Trigger: A core.yaml externalBuilders list entry that specifies a name (and possibly environment/propagateEnvironment) but no path key, or whose path value is empty/whitespace after env expansion.

Common situations: Hand-editing core.yaml and forgetting the path key; copying a builder stanza from docs with placeholders left blank; templating/Helm charts that render an empty path variable; YAML anchor merge accidentally dropping the path field.

Related errors

• external builder at path %s has no name attribute
• peer.address isn't set
• error unmarshalling YAML
• Error reading configuration: %s
• %s is mandatory and cannot be empty

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/e068845ea6d56633. Report an issue: GitHub.