M-Files Essentials troubleshooting
Headings here are symptoms — what you see — rather than causes.
Every utility is off by default and acts at check-in, which is why most reports of a utility doing nothing are one of the first three things below.
Check these first
Section titled “Check these first”- Is the utility enabled? It is off by default, and the switch is the one thing a person fills in the settings around and then forgets.
- Is the licence valid? Without one the utilities do not run. The application still installs and its configuration still opens, so an unlicensed vault looks like a working one.
- Has the object been checked in since? Most of these act at check-in. Nothing changes on objects that have not been touched since the utility was switched on, and there is no backfill.
- Does the application status report an error? M-Files Admin shows the application’s own validation under the vault’s Applications node.
A utility does nothing
Section titled “A utility does nothing”If the four checks above did not explain it, the utility is running and deciding not to act.
The trigger does not match. The condition is evaluated against the object being checked in. An empty condition matches everything of the configured type; a condition naming a property the object does not have matches nothing.
The object is the wrong type. A utility with object type mappings only acts on the types it has a mapping for, and falls back to the default value — which may be empty — for the rest.
A setting names something that has been deleted. An object type or property removed from the vault after the utility was configured shows up in the application status in M-Files Admin.
A generated value came out wrong
Section titled “A generated value came out wrong”Half of it is missing. A placeholder naming a property the object does not have expands to nothing rather than failing. Read the value on a real object rather than the pattern.
It is the default rather than the pattern. No mapping matched. Check the object type mapping exists for that type, and that the condition on the mapping actually holds.
It changes when it should not. Auto Name recalculates on each check-in by design. For a value that has to stay fixed once assigned, use Auto Identifier instead.
Two utilities fighting over one property
Section titled “Two utilities fighting over one property”Nothing prevents two utilities from writing the same property, and the outcome depends on the order they happen to run in. The symptom is a value that is correct sometimes and not others, with no pattern to it.
Give each utility its own target property. If two genuinely need to contribute to one value, have one of them write to an intermediate property and the other read it.
A check-in is refused
Section titled “A check-in is refused”Metadata Validation refuses a check-in that breaks one of its rules, and the message says which rule. Two cases are worth knowing:
A uniqueness rule against a generated identifier. If Auto Identifier’s pattern is not actually unique, the first collision surfaces as a refused check-in on an unrelated object.
A date rule reading as an equation. The date rules are of the form source operator (target + offset). A rule that looks backwards usually is: swap source and target rather than negating the offset.
Check-in became slow
Section titled “Check-in became slow”Every enabled utility whose trigger matches does work on each check-in. One is negligible; a dozen with broad conditions is measurable.
Narrow the trigger conditions first — a condition matching one class costs far less than one matching every object. If it is still slow, disable utilities one at a time to find the expensive one.
A scheduled utility is working through the whole vault
Section titled “A scheduled utility is working through the whole vault”State Duration and External Refresh run on a schedule rather than at check-in, so switching one on starts it working through objects that already exist. On a large vault the first run is long. That is expected; it settles once it has caught up.