Template Troubleshooting
Decoding the errors template updates actually throw — key not present, duplicates, stray measures, and instances that fault after an update.
Templates: Instantiating and Updating covers doing it right. This article decodes what you see when an operation goes wrong — these errors account for a large share of all template support traffic, and most have a mechanical cause.
"The given key … was not present in the dictionary"#
The most common template-update failure. The update builds maps between template members and instance members, then reads them; the error means the update expected an entity in its mapping that was not there.
Practical causes, most likely first:
- A member was added to the template and the instance has never seen it — combined with a partial or interrupted earlier update, the mapping is out of step. Update the parent level (the containing folder or metric), not the individual member.
- Something was deleted on one side — a measure removed from an instance, or a template member removed after instances were created.
- The scope is too narrow. A recursive update at a high level can fail where updating the individual sub-folders succeeds — because the wide scope pulls in a mapping the narrow one avoids. As a workaround, update one level down; as a diagnosis, the entity the wide scope trips over is your culprit.
When it persists: identify the specific instance by updating instances one at a time until one fails, then compare that instance's members against the template member-for-member. The mismatch is usually visible.
Duplicate or " - Copy" entities after an update#
Matching during import/update works by identity first, then by name within the container. Two candidates with the same name in one container are ambiguous, and the ambiguous path creates a new entity — historically with a - Copy suffix.
Prevention is naming hygiene: no two siblings with the same name, and instantiated-name patterns that cannot collide (a pattern that resolves identically for two instances will collide — check the attribute values feeding it).
7.2.0 note: the bug that appended - Copy to descriptions when instantiating multiple copies is fixed.
Stray members appearing at the wrong level#
Updating a folder and finding metrics or events from a sub-folder duplicated into the parent is a known historical defect class, improved in later versions but worth recognising: the strays are new entities, not moves. Delete the strays at the wrong level; the originals are intact. If it recurs on a specific structure, update the sub-folders individually rather than the parent recursively, and report the structure — reproductions of this class are valuable.
Instances fault after an innocuous template change#
A description edit or property tweak, released and updated, and instances go to Faulted with nothing in the event log. Two things to check:
- Was the template re-released? An un-released template can leave instances mid-version.
- Deploy state. An update touches the instance's configuration; an object left Different is running the old config while the model holds the new one — the mismatch can present as faulting on the next deploy rather than at update time.
Undeploy/redeploy of the affected engine clears the transient form of this. If it does not clear, the change was not cosmetic — diff the template version history.
Updates that delete more than expected#
Two distinct cases:
- Calculation instances deleted by an update — a real defect in earlier versions when a locked-retrieval template updated over instances carrying user-added calculations. Fixed in 7.2.0: user-added calculations now survive locked-retrieval updates. On older versions, the workaround is to delink the calculations' metric before updating.
- Delink-instead-of-update at partial scope — when the update payload does not include a templated child's parent, some paths have wrongly delinked out-of-scope siblings. If instances silently stop receiving updates after a partial-scope operation, check their template linkage before anything else.
Renames and moves#
Renaming a template member then updating matches by name — so the instance member with the old name is not matched, and you get an add (new name) plus an orphan (old name), not a rename. Rename on both sides, or accept and clean up the orphan.
Moving a folder of metrics within the template then updating the template side of a downstream instance is sensitive to order: update the destination parent first, then the source parent, so the move is seen as a move rather than a delete-and-add.
A one-page checklist when an update fails#
- Re-release the template — an edit un-releases it silently.
- Retry one level down from where it failed.
- Find the single failing instance by updating instances individually.
- Compare that instance's members to the template's, name by name — look for duplicates, missing members, renames.
- Check linkage: is the instance still templated, or was it delinked by an earlier partial operation?
- Check the calendars — a calendar mismatch produces its own error family: Templates Across Calendars.
- Take a model export of the template and the failing instance before attempting fixes, so the broken state is preserved for support.