CtrlShare troubleshooting

Sections here are titled by symptom — what you see — rather than by cause.

CtrlShare reports a refused command in the dialog the user was standing in, with a copyable error report behind it. Everything that happens without a user watching — a token refresh, a workflow-driven check-out, a person who could not be resolved — is reported only in the vault application log, so that is the second place to look and often the first.

Check these first

1. Has the Entra ID client secret expired? This is the most common cause of a deployment that worked for a year and then stopped. Nothing warns you in advance; sessions fail to start with an authentication error. Check the expiry date in the Entra admin centre.
2. Has the OneDrive authorisation expired? It expires on its own schedule, separately from the client secret, and with no warning either. Re-authorising is Add a OneDrive account, steps three to six.
3. Was the vault restarted after installation? The application does not start until it is, and the restart does not begin until the Applications dialog in M-Files Admin is closed.
4. Is there a localisation entry, and is one of them the default? The server sends a client only the entry matching the user’s M-Files language, or — when none matches — only the entries marked default. With no entries, or with none marked default, such a user is sent an empty list and the client registers no commands.
5. Is TLS 1.2 enabled on the server? Older Windows Server builds default to TLS 1.0, which Microsoft Graph refuses.

No CtrlShare commands appear on a document

Command visibility is decided per document and per user, so “no commands” has several distinct causes. Work down them in this order.

The vault has not been restarted since installation. Nothing runs until it has.

The Entra credentials have not been entered. Check Out to OneDrive stays hidden until Client ID and Client Secret both hold a value. This is deliberate: a document that is already checked out stays releasable while credentials are missing or being rotated, so a half-configured vault can show Check In from OneDrive on one document and no command at all on another.

The user is outside the whitelist. Under Access Control, an empty Whitelisted User Groups list means every licensed internal user may co-author. A list that has rows but names no group in any of them closes the gate for everybody — a whitelist that was started and never filled in fails closed. Whitelisted Conditions behaves the same way for documents: no rows means every compatible document is eligible, rows with no conditions in them mean none is.

The document does not match the conditions whitelist. Only documents matching at least one row may be checked out, and the check runs per document, which is why the command appears on some documents and not others.

The licence does not cover the user. A restricted licence names user groups and a seat count for each; a user outside those groups, or in a group whose membership has grown past its seat count, gets no commands. An invalid licence removes them for everyone.

The user’s language has no localisation entry, and none is marked default. The server sends a client only the entry matching the user’s M-Files language, or the entries marked default when none matches. A user who gets neither is sent an empty list, and the client registers no commands — for that user only, which is what makes it look like a permissions problem.

An older CtrlShare user-interface bundle is installed next to a newer server. The two agree on a contract version, and a bundle that predates it is handed an inert payload: it shows no commands and raises no errors. Reinstalling the application package puts both back in step, because the vault application installs its own interface bundles.

The configuration could not be loaded at all. The log carries one line reading the CtrlShare configuration is missing or could not be loaded; co-authoring guards are disabled until it is repaired, written once per vault start. Until it is repaired, CtrlShare stands aside entirely rather than blocking every check-out in the vault.

Check out to OneDrive is refused before anything happens

These four refusals all arrive before the document has been touched in M-Files, so there is nothing to undo afterwards.

This Drive Configuration has not been set up. Please contact your administrator!

The OneDrive for Business section is missing, or its client ID and secret are blank. Enter them, then complete the authorisation.

No OneDrive for Business token found in system, check that RefreshDaemon is configured and running.

Credentials are present but no authorisation code has ever been redeemed for them, so there is no token to act with. Work through Add a OneDrive account.

The External File ID Platform property is not set up correctly. Please refer to the setup guide for more information.

The value list behind the External File Platform property holds no item named OneDrive for Business. The name is fixed in the application and matched without regard to case; every checked-out document is stamped with it. Add the value list item as described in Vault structure.

The current user does not have edit rights on this document!

One of several M-Files-side conditions: the user cannot edit the object, the user is external, the vault is in read-only access, the user’s own M-Files licence does not allow modifications, or the CtrlShare licence is invalid or its seats are exhausted.

Check-out worked for a year and then stopped

The connection keeps itself alive by refreshing its token roughly every thirty minutes. When a refresh fails it retries after one minute, then five, then fifteen, then every thirty, and writes Error refreshing authentication for OneDrive for Business each time. Once the stored token can no longer be refreshed, check-outs fail.

Two things expire and neither announces itself: the Client Secret in the Entra registration, and the OneDrive authorisation the connected account granted. Renew the secret first and paste the new value into Client Secret — the stored refresh token is untouched by that, and refreshes usually resume on their own. If the log keeps reporting refresh failures afterwards, the authorisation itself has gone and the account has to be re-authorised.

A third line is worth recognising: Token refresh skipped: OneDrive for Business client id / secret not entered; keeping the stored token. The credentials have been cleared while a token is still stored. Documents already out can be checked in; no new session can start.

Re-entering the same authorisation code does nothing

Entra authorisation codes are single-use, and CtrlShare compares the code you save against the one it last redeemed — with or without the redirect URL wrapped around it. Saving the same code again is not a new authorisation. Take a fresh code from the consent flow each time.

A document cannot be checked out, or cannot leave its state

M-Files shows one of two messages, in the user’s client language:

This document is open for co-authoring and cannot be checked out or edited in M-Files.

To continue, select the document and run CtrlShare → "Check In from OneDrive". That saves the
co-authored version back into M-Files and releases the document.

To discard the co-authored changes instead, run CtrlShare → "Undo Check Out to OneDrive".

This document is open for co-authoring and cannot leave the "<state>" state.

Both are working as intended: while a session is open the document is held, and the second variant names the workflow state it is held in. The command names inside the message come from the localisation entry, so they match what the user sees on the document.

Neither message is an error to fix. The document is released by running Check In from OneDrive or Undo Check Out to OneDrive on it.

An automatic workflow transition no longer fires

A document in a mapped co-authoring state cannot leave that state, and the refusal applies to automatic transitions and to system accounts as well as to users. The log records Workflow exit blocked while co-authoring, with the workflow, both state IDs and the object version.

This changed in 2.26.7.6. CtrlShare used to try to retrieve the document itself when the state changed, which only ever succeeded when the M-Files server made the change. The transition is now refused instead, so a workflow can never advance over content that exists only in the co-authoring copy.

If a workflow has to advance automatically, either take that state out of Workflow Mappings, or give the transition a pre-condition requiring the External File ID property to be empty.

Entering a mapped state did not check the document out

The automatic check-out runs after the document version is finalised. It is skipped for templates and for objects with no workflow, and everything else is in the log under the mapping’s Name — which is why a mapping is required to have one.

• Auto workflow entry detected and then nothing: the check-out was attempted. Look for Auto checkout+share failed or Auto workflow entry failed beneath it, which carry the underlying error.
• Auto workflow entry resolved no editors or viewers (source lists empty or unresolved); checking out without sharing: the document was checked out, but the properties named in Editor Source Properties and Viewer Source Properties were empty or resolved to nobody. No one was invited, and people can still be added afterwards with Share.
• workflow mappings target workflow …, state …; the first mapping will be used: two mappings point at the same state. Only the first acts; the others are ignored.

Somebody was left out of the share

The share list is built by resolving each person reference through the person mappings, and a reference that cannot be resolved is dropped rather than failing the whole share. The log names each one — Could not resolve email for person …, Person search failed for mapping ….

No email address could be found. OneDrive is invited by email address, so a person object with an empty Email Property cannot be shared with. Setting User Account Property as well gives the resolver a fallback: the email address on the linked M-Files login account.

The property is not covered by any person mapping. The log says No Object person mapping matches object type …; skipping reference …, or No person mapping can resolve user …; skipping. The document names people of a kind no mapping describes — typically a viewers or editors property added to a class after the mappings were configured.

A restricted licence excluded them. Where the licence names groups and seat counts, a person who does not resolve to a licensed M-Files user is dropped from the share, and from the people search that feeds the sharing dialog. Members of a user group are filtered one by one on the same rule.

The sharing dialog finds nobody at all. The people search returns an empty list, without an error, when the CtrlShare licence is invalid or the searching user is outside Whitelisted User Groups. A mapping’s Search Conditions narrow it further — a condition restricting results to active Person objects hides everyone else.

Somebody appears as a viewer when they were named as an editor. Deliberate: a person in both lists is invited once, as an editor. Before 2.26.7.6 they received two invitations and kept whichever arrived last.

Sharing with somebody outside the organisation fails

Microsoft 365 refused the sharing invitation. This usually means external sharing or guest
invitations are not allowed for this tenant or for the connected account

Every invitation runs as the connected OneDrive account through OneDrive’s own invitation flow, and for an external recipient that provisions a Microsoft Entra guest. The tenant has to permit both halves:

• SharePoint and OneDrive external sharing set to at least New and existing guests, at the site level as well as the tenant level.
• Entra ID → External Identities → External collaboration settings permitting the connected account to invite guests, either because member invites are allowed or because the account holds the Guest Inviter role.
• Email one-time passcode authentication enabled. It is on by default.
• Domain restrictions checked twice: SharePoint’s sharing domain allow and block lists, and Entra’s B2B collaboration restrictions, both gate the invitation.

GCC, GCC High and DoD tenants remain on Microsoft’s legacy sharing model, where an ad-hoc external recipient cannot edit in Office. External co-authoring is not supported there.

Check in fails

The document is still being edited by another user. Please ask them to close it and try again.

OneDrive refused to lock the file because an Office session still has it open. Nothing in M-Files has changed. Ask the editors to close the document, then retry.

The item is locked for editing. Make sure that no-one is editing it currently

The same lock, reached one step later while the file was being downloaded. The M-Files check-out that had been taken is rolled back, so the document is left as it was.

The item could not be found in OneDrive.

The working copy no longer exists — deleted from the service account’s OneDrive, most often by hand. CtrlShare clears the co-authoring properties and checks the document back in so the vault stops pointing at something that is gone, but the version it checks in is the content M-Files already had. Anything edited in OneDrive after the check-out is not recoverable through CtrlShare.

Checkout undone; OneDrive cleanup deferred.

This one is reported as a success, and it is one: the undo completed in M-Files. Deleting the OneDrive copy afterwards failed, so an orphaned file is left in the service account’s OneDrive. The document itself is fine.

A document stays checked out after the person who started it has gone

Sessions are open-ended by design — a document stays out until somebody runs Check In from OneDrive or Undo Check Out to OneDrive. There is no timeout to wait for.

Release it with one of those two commands rather than by undoing the check-out in M-Files Admin. CtrlShare decides that a document is out for co-authoring from its External File ID property rather than from the M-Files check-out, so undoing the check-out in Admin leaves the property set and the OneDrive copy in place, and the document goes on refusing check-out and workflow transitions.

A document is checked out to a platform this version does not support

This document is checked out to "…", which this version of CtrlShare does not support
(OneDrive for Business only). Please contact your administrator.

The document was checked out by a configuration that used something other than OneDrive for Business, which versions before 2.26.8.0 allowed. The current version refuses to act on it rather than look for it in the wrong service, where the request would come back as not-found and the document would be checked in with stale content.

Retrieve the file from wherever it actually is, then clear the External File ID and External File Platform properties on the document. With no External File ID, CtrlShare no longer treats it as being out for co-authoring.

Track Changes was not turned on

Three conditions have to hold, and the log line written on every check-out and check-in reports each of them: whether the property is configured, whether the document requested it, the file extension, and whether the file was Word OOXML.

• Track Changes Property has to name a yes/no property, and that property has to be on the document’s class.
• The property has to be set to Yes on the document before the check-out. It is a per-session request, cleared when the session ends, so each round starts from an explicit decision. Where the class requires the property, it is reset to No rather than left blank.
• The file has to be Word OOXML — docx, docm, dotx or dotm. Excel, PowerPoint and legacy .doc files are passed through untouched.

The configuration looks wrong after upgrading to 2.26.8.0

The upgrade to the OneDrive-only configuration runs on the first vault start after installation and rearranges an existing setup rather than asking for it again. No re-authorisation is needed: the connected account’s token is stored outside the configuration and is not touched.

To confirm it ran, look for the configuration upgrade entries in the vault application log, and check that the stored configuration in Named Value Storage (ControlledCoAuthoring.VaultApplication / configuration) is stamped "Version": "3.1" and holds an OneDriveConfiguration section.

Two things change visibly. Workflow mappings carried over from 2.26.4.2 and 2.26.6.0 arrive with generated names — Workflow mapping 1 and so on — because a mapping now needs one; rename them at your convenience. Any legacy drive entry that was not OneDrive for Business, and the former folder check-out settings, are discarded, and the log says so.

The upgrade also writes the connection’s existing Redirect URI into the configuration, so an existing connection keeps working with the address it was authorised against. Only a vault with no client ID yet starts on the new default, http://localhost/ctrlshare.

preventCheckout is not carried over. An M-Files check-out of a document that is out for co-authoring is now always blocked, with the configurable block message. Release the document with Check In or Undo Check Out first.

The pre-upgrade configuration is kept

CtrlShare copies the previous configuration into Named Value Storage under ControlledCoAuthoring.VaultApplication.Backup / configuration-before-3.1 before migrating, and never overwrites it. Rolling back means reinstalling the previous version and restoring that copy — not deleting the version stamp from a migrated configuration.