Pitfalls

The most dangerous pitfall produces no diagnostic at all: cfu cfg validate reports success, but your file was never discovered, because it lies outside the workspace, above a workspaceRoot, or in a folder whose .confu sets ignoreTraversal: true. Everything looks green while the product runs without your configuration.

After creating a file, and whenever a reported result surprises you, run cfu workspace list and confirm the file appears in the discovered file tree.

A configuration file without $definition cannot be bound and fails with Missing '$definition'. The value is the definition name (definitionName) followed by @ and the version, not the definition’s file name or path. cfu def list prints the names of the workspace.

An entity carries name or id, never both. Both must match ^[A-Za-z][A-Za-z0-9_]*$; hyphens and a leading digit are the common violations. Remember that an id must be globally unique, while a name only identifies the entity among its siblings.

In mergeable modes, entities merge by identity. name: "Body" in one file and name: "body" in another create two channels instead of one, and the error appears somewhere else, as a duplicate, a failed reference, or a multiplicity violation "across merged files". When a merge result surprises you, cfu cfg export-merged --with-origin shows what merged into what.

Two files setting the same value differently is an error unless one has the higher $fileType priority. If you meant to override, raise the overriding file (for example to UserConfigPriorityHigh); if not, remove one of the values. Do not resolve conflicts by copying the same value into both files; that just defers the conflict to the next edit.

DefaultValues* types belong to .default.def.json5 files and PreConfiguration* types to .preconfig.def.json5 files, both provided by the definition author. In a .cfg.json5 you can use the UserConfig*, Generated*, and UserOverride types; anything else is an error.

$path / $type extend an entity another file or a mixin declares. They never create one. No configuration file or mixin declares the entity at path …​ means the path resolves to nothing, or only below a fragment whose own anchor does not resolve, so the whole file would be lost. The message suggests a near miss when there is one, and IDE completion on $path only offers paths that exist. The other half of the same mistake is a path whose first segment is wrong: it is the document root’s name, which is the definition name unless some file sets a top-level name.

$mixin is a mixin’s name filter, not part of what makes one, so forgetting or misspelling it raises no error at all: the mixin then applies to every element of its $type, turning one element’s settings into the whole definition’s. Hover a value inside a mixin body to see the elements it currently applies to, and read a $mixins entry without $mixin as a deliberate class-wide default.

If a union value matches several alternatives, or an object union arrives without a discriminator, validation asks for $type. Its value is the full path DefinitionName::TypeName, for example SensorEcu::AnalogInput; the bare type name is not enough. Primitive unions are the opposite: they take the bare value and no $type at all.

A reference path is built from entity identities (name, else id, else type name), not from the property names in the definition. Writing /SensorEcu/ecu/sensors/OilTemp fails; the path is /SensorEcu/FrontBodyEcu/OilTemp. Let IDE completion build the path, it only offers valid targets.

References and merges bind to the identity string. When you rename an entity, every reference path containing the old name breaks, in your file and in every other file of the CfgSpace. Validation finds them all; fix them in the same change. The safest identities are the ones you never need to change, so name entities after their role, not their current value. Or use the IDE to rename entities, which will also rename the references to it.

A single scalar without brackets is accepted only for parameter lists. An entity or struct list always needs the array, even with one element: sensors: [{ …​ }], not sensors: { …​ }.

The version in $definition: "Name@version" is required. A later definition of the same major (0.x: the same minor) accepts it, a new major or an older definition is an error. When a definition update reports one, do not just edit the number to silence the diagnostic: the definition’s rules have changed under your configuration. Review what changed, adapt the configuration if needed, then update the version.

$fileType, $path, $mixins and $applyMixins exist only for definitions that merge entities across files, and $fileType only in the priority mode. The same key that is correct in one project is therefore rejected in the next one, with a message naming the mode. cfu def list prints the mode of every definition, and How the Features Work Together has the matrix of what each mode allows.