Here you will find an explanation and best practices for solving Business properties-related synchronization errors.
In design files, element attributes, also called Business properties, provide important information about various elements within the design. These attributes are used to define and describe elements and use this information to calculate various other parameters, such as element amount.
Read more about ECschemas and their purpose.
Error message: Failed to validate ECSchema <schema name> as an EC3.1 ECSchema.
Issue:
The source file contains a business-property definition (a data schema describing the properties attached to elements). While preparing that definition for the iModel, the synchronizer converted it into the format the iModel requires, but the converted definition did not pass validation. Because the definition is not valid, it cannot be brought into the iModel.
Cause:
Effect:
Solution:
Additional Information:
Error message: "Failed to convert [Could not read v8 ECSchema XML for FileName from c:\stagingdir\A.i.dgn (ElementId: 30)"
Issue:
The business data or element information is missing in the iModel Viewer.
Cause:
Solution:
Error message: "Ignoring <SchemaName> on element <...> in file because the schema failed to de-serialize."
Issue:
There is an inconsistency in the schemas between the various attachments.
Cause:
When master file and attachment or reference file contains different versions of schemas' this inconsistency causes connector to ignore loading schema.
Solution:
Either change the reference file or master file to use the same schemas' version.
In example master file contains IntegratedStructuralModel.X and OpenPlant_3D.Z which references that IntegratedStructuralModel.X. And other attachment in the same iModel contains OpenPlant_3D.Z which references different version of IntegratedStructuralModel.Y. This inconsistensy causes the connector to fail to properly load OpenPlant_3D.
MicroStation documentation related to EC schemas: https://docs.bentley.com/LiveContent/web/PlantWise%20Help-v4/en/GUID-57326976-317C-44C7-A554-336A840EC5DD.html
More information about schemas: https://www.itwinjs.org/bis/guide/schema-evolution/schema-customization/
How to update Schema of a DGN file: https://bentleysystems.service-now.com/community?id=kb_article_view&sysparm_article=KB0111879
OpenPlant PID Schemas upgrading: https://bentleysystems.service-now.com/community?id=kb_article_view&sysparm_article=KB0101747
Warning message: Failed to read supplemental ECSchema from file '<file name>'.
Issue:
While preparing the business-property definitions found in the source data, the synchronizer looked in the configured schema folders for supplemental schema files. A supplemental schema adds extra information (such as units, display labels, categories, and formatting) to a main schema. The synchronizer found a supplemental schema file but was unable to read it, so the extra information that file would have provided is not applied.
Cause:
This message is typically produced for one of the following reasons:
Effect:
This is a warning; the synchronization continues.
Solution:
Additional Information:
This message relates to reading supplemental schema files found in the configured schema folders. Other related messages report problems applying supplemental information to a specific schema or working with supplemental schema details.
Warning message:
Could not locate the following external V8 ECSchemas. Instances of classes from these schemas will not be converted. <Schema name>
Issue:
During conversion of a DgnV8 file to an iModel, the connector references one or more external ECSchemas — schemas that are stored separately from the DGN file rather than embedded in it. This warning is raised when one or more of those external schemas cannot be located in the conversion environment. Because the schema definition is missing, any business data (EC instances) belonging to classes from that schema are skipped and does not appear in the resulting iModel. The conversion itself is not stopped; it continues and completes with this warning.
Cause:
Effect:
Solution:
Additional Information:
"External" schemas are those stored outside the DGN file, as opposed to schemas embedded (stored) within the DGN itself. Only the external schemas that could not be resolved are listed in the message.
Reviewing the listed schema names indicates exactly which business data was skipped, which helps identify the source application or workspace that should provide the missing schema.
Warning Message: Multiple copies of schemas were found. This can result in inconsistencies between the iModel and the original file. To resolve this, please review the source data and ensure all schemas are the same. <Schema Name>
Issues:
The following warning occurs when the synchronization process detects multiple copies of the same ECSchema within the source data:
DgnCustomItemTypes_STATIONING
DgnCustomItemTypes_PHASING
DgnCustomItemTypes_REVISIONS
DgnCustomItemTypes_0210-SUBGRADE
DgnCustomItemTypes_0410-WEARING COURSE-ASPHALT
DgnCustomItemTypes_0601-PIPE CULVERTS
DgnCustomItemTypes_1200-INTELLIGENT TRANSPORTATION SYSTEM (ITS) DEVICES
Cause:
The synchronization process converts DGN Item Types into ECSchemas and synchronizes them as iModel Business Properties.
This warning is generated when multiple copies of the same schema name are discovered within the source dataset and those schema definitions may not be identical.
Common causes include:
Since the connector cannot determine which schema definition should be authoritative, it reports the warning to prevent potential Business Property inconsistencies.
Solution:
Review the Affected Schemas:
Identify the schemas listed in the warning message and determine which source files contain them.
Check Reference Files:
Review all attached and referenced DGN files. Ensure they use the same Item Type definitions and schema versions.
Verify DGNLIB Consistency:
Confirm that all project files are referencing the same DGNLIB and that Item Type libraries have not diverged over time.
Compare Schema Definitions:
Inspect the affected schemas and verify that property names, property types, enumerations, and custom attributes match across all files.
Update ProjectWise References:
If ProjectWise is being used, ensure all files are checked in, refreshed, and synchronized against the correct versions.
Remove Duplicate Definitions:
Where practical, remove obsolete or duplicate Item Type definitions and standardize on a single source of truth.
Republish Resynchronize the iModel:
After correcting the source data, perform a fresh synchronization and confirm that the warning no longer appears.
Validate Business Properties:
Review the resulting iModel and verify that all expected Business Properties, Item Type values, and Data Visualization workflows behave as expected.
Best Practices:
Info Message: The connector reports this issue when it cannot convert an ECRelationship because the target end of the relationship could not be resolved in the iModel. The message appears in one of two forms:
Example: Could not convert ECRelationship BuildingSchema:BeamHasMaterial from element 1103 in model Default in file 'Sample.dgn'. Target element 56706 in model Structural was ignored.
Issues:
An ECRelationship in the source DGN links a source element to a target element. During relationship conversion the connector tries to locate the target element's converted counterpart (its mapped model and instance) inside the iModel. When the target cannot be resolved, the relationship is skipped and is not created in the iModel. This can result in:
The synchronization continues normally — this is reported at an Info severity because it is expected in some datasets and does not stop the synchronization. When the second form ("was ignored") is reported, the relationship is also counted as an ignored relationship.
Cause:
During the ECRelationship conversion, the connector resolves both the source and target endpoints of each relationship to their converted elements. DgnV8_0181 is raised specifically for the target endpoint in two situations:
Because the target endpoint does not exist in the BIM, the relationship cannot be created and is skipped
Solution:
Best Practices:
Error message: "Dropping base class [Class NAME] from [Item Type= Name: Name OF Parameter Set] because the base class is defined in a schema set to be pruned in the schema read context."
Issue:
Coming soon.
Cause:
Coming soon.
Solution:
Coming soon.
Warning message: Skipped v8 <class name> ECInstance (<id>) on v8 Element '<element>' in v8 model '<model name>' because its class was ignored during schema conversion. Instances of Struct or CustomAttribute type are not supported on their own, they can only be used within the context of another class.
The message names the piece of business-property data that was skipped, and the element and model it was attached to.
Issue:
Your DGN elements can carry business properties (data fields attached to them). During synchronization, one of these pieces of attached data used a type that can only exist inside another set of properties — not on its own. There are two such types: a Struct (a group of fields meant to sit inside a parent record, like an "address" block inside a "person") and a CustomAttribute (a special marker used to describe other data, not a stand-alone value). Because this data was attached directly to the element instead of being nested inside a normal property set, the connector cannot store it and skips that item.
Cause:
A Struct value was attached directly to an element instead of being nested inside its parent property set.
A CustomAttribute value was applied at the element level in the source data.
Authoring tools or an earlier data migration produced stand-alone data of a type that is only meant to be used inside another class.
Effect:
This is a warning only — synchronization continues and completes normally.
Everything else on the element (geometry and other properties) is synchronized as usual.
Only the skipped value is left out; it will not appear as a property on the corresponding element in your iModel.
Solution:
Additional Information:
Seeing this warning many times usually means one authoring pattern is repeated across many elements — not many separate problems. Fixing it once at the source typically clears all of them.
Warning message: "Element cannot be included into [Element 1 Name] to follow [Element 2 Name] relation as it's already part of another Model Group [Model Group Name].
Issue:
Relationship between a Revit element and its parent Model Group cannot be set.
Cause:
Revit Model groups are a Revit feature for designers to group repeating sets of elements, such groups are not preserved in iModels, so their relationships with their elements cannot be set.
Solution:
Due to improvements in the Revit connector, the next time this model is synchronized, the group element will be removed and this warning will no longer appear.
Issue:
Display labels are not updated in the iModel properties.
Cause:
When a source file schema is updated and then re-synchronized into the iModel, the iModel connector does its best to merge the incoming changes with the existing schema. However, Display Labels (whether for schemas, classes, properties, standard values, etc.) are not updated.
Solution:
At the moment this issue can not be resolved by yourself. If you need to force the update of a display label, please contact Bentley Support. A flag can be set on your project that will allow updating of the display labels.