PDS troubleshooting

PDS reports a failure in one of two places. A check that runs as the project enters a state refuses the transition, with a message that says what is missing. A failure in the background work that follows usually moves the project to an error state and writes the reason to the project’s Error Property; the exceptions are under The project stays in the Generate Baseline or Activate state. Either way, read the message before anything else.

The exception is the failures that happen before the handlers run at all. Those are silent from the user’s point of view and only visible in the application log.

Check these first

1. Read the message. A refused transition says what is missing. A project in Baseline Generation Error or Activation Error has the reason in its Error Property. That answers most reports on its own.
2. Is the licence valid? Without one the check-in handler that drives everything is disabled, and nothing at all happens.
3. Does the application status report a configuration error? M-Files Admin shows it under the vault’s Applications node. PDS refuses to run its handlers while the configuration is invalid.
4. Is CtrlSync installed, configured and licensed? PDS reaches SharePoint through it and refuses to activate a project when it cannot.

Nothing happens at all

Two conditions disable PDS’s check-in handler entirely. Neither shows up in the client: the project moves between states and nothing is generated.

The licence is missing or invalid. The log records No license detected or Invalid license detected at startup, and License invalid, check-in handler disabled on each check-in. Apply a valid .lic file.

The configuration is invalid. The log records Configuration invalid, check-in handler disabled. The application status in M-Files Admin says which setting is at fault — usually a required setting naming an object type, property or state that no longer exists.

Check the application status first

M-Files Admin shows the application’s own validation results under the vault’s Applications node. A configuration error there explains almost every case of PDS doing nothing.

Baseline generation is refused

These messages appear on the refused transition into the Generate Baseline state. Nothing has been created.

Message	What it means
Project missing a template!	The project’s template property is empty. Set it to a project object template.
Project Template X missing a directory structure!	The named project object template has no directory structure property set.
Document Object Template 'X' had no directory structure assigned!	The named document object template needs its directory structure property set.
Document Object Template 'X' had no full path assigned!	The named document object template has no path object saying which folder its document belongs in.
Document Object Template 'X' had no document template!	The named document object template does not reference a document to copy.

All of these are missing references on template objects rather than configuration mistakes. Fix the object the message names and retry the transition.

The project moved to the Baseline Generation Error state

The transition succeeded and the background task that creates the artefacts then failed. The project’s Error Property usually contains One or more DocumentObjectTemplates could not be converted into artifacts: and the templates concerned, followed by each one’s own error.

The artefacts that were created stay in the vault. PDS runs the generation again a minute later, and again after each further failure, up to five more times. A run that fails again overwrites Error Property with its own error; one that succeeds moves the project to Baseline Generated by itself.

If the project is still in this state after that, fix the templates the message names, then move the project back into the Generate Baseline state: PDS creates artefacts only for the document object templates that do not have one yet.

Activation is refused

These appear on the refused transition into the Activate state. Nothing has been sent to SharePoint.

Cannot create SharePoint artifacts until CtrlSync is installed, configured and licensed.

PDS asked CtrlSync for its status and did not get a positive answer. This is about CtrlSync, not PDS: check that it is installed in the same vault, that its configuration is valid, and that its licence is current. See CtrlSync troubleshooting.

No Sharepoint Url attached, please fill out the … property on the project

The project has no SharePoint URL. PDS needs to know where to upload before it will start. The message names the property, which is the one set as the SharePoint URL property in Graph Configuration.

The project moved to the Activation Error state

The checks passed and the background upload then failed. The project’s Error Property holds the reason, and Sync Is Active Property has been set to No. A failure in one or more uploads contains One or more artifacts failed to upload: and the artefacts concerned, followed by each one’s own error:

Error	What it means
SPO artifact X had no document template to refer to!	The artefact has lost its link to a document object template.
Document template X had no underlying file!	A document template object exists but nobody attached a file to it. This is the common case.
Document template had no Path object assigned.	The document object template has no full path.
Document Version Property is not a lookup or multi-select property	Version Property under Document Templates Configuration has the wrong data type. It has to be a lookup or multi-select lookup.
Object reference not set to an instance of an object.	Version Property is empty, or a document object template no longer references a document template. PDS needs Version Property whenever it uploads artefacts.

Folders and documents that were uploaded stay in SharePoint, and their artefacts are in the artefact workflow’s Activated State. The ones that failed are in its Error State. An artefact in the Error State can already have Version Property set; that does not mean it was uploaded.

PDS runs activation again a minute later, and again after each further failure, up to five more times. A later run uploads only artefacts in the Generated State, so it skips the failed ones and can move the project to Activated without those documents, often within a minute of the failure. A project that has left Activation Error can therefore still have artefacts in the Error State; see The project is activated but a document is missing from SharePoint.

To retry, fix the cause and move each failed artefact back to Generated State before moving the project back into the Activate state. Otherwise the retry skips it again.

A folder that CtrlSync cannot create does not fail activation. CtrlSync logs it and carries on, so a folder missing from SharePoint shows up in the CtrlSync log rather than on the project.

The project is activated but a document is missing from SharePoint

The document’s upload failed, and a later run of activation then finished without it. An artefact whose upload fails moves to the artefact workflow’s Error State, and every run uploads only artefacts in the Generated State, so the later run skipped that artefact and moved the project to Activated.

Look among the project’s artefacts for any in the Error State. The reason is the earlier error in the project’s Error Property, which PDS does not clear when the project reaches Activated; the table under The project moved to the Activation Error state says what each message means. With Sync Is Active Property empty, PDS writes nothing to Error Property and the reason is only in the PDS log.

Fix the cause, move each of those artefacts back to Generated State, then move the project into the Activate state again. The workflow needs a transition from Activated into Activate for that.

The project stays in the Generate Baseline or Activate state

Both steps run as background tasks from a queue PDS polls every ten seconds, and the project stays in the state until its task has finished. The application’s dashboard in M-Files Admin lists each run under Project Baseline Generation or Project Activation, with its progress.

A task that has finished without moving the project did not record its outcome. Two things cause that:

• Activation failed with Sync Is Active Property empty. The task stops before it writes Error Property or moves the project to Activation Error, and the reason is only in the PDS log. Configuring Sync Is Active Property lets PDS record the failure on the project.
• The licence stopped being valid after the transition. The task does nothing and logs License invalid, cannot run Project Baseline Generation. or the same for activation.

Files went to the wrong place

The folder an artefact lands in comes from the path object chain, not from anything typed in. Walk it: the document object template’s full path property names one path object, that object’s partial path title is the folder name, and its directory structure property names its parent. A folder appearing at the top level when it should be nested means the parent reference is missing.

A document was checked out and PDS worked anyway

PDS undoes a checkout it finds in its way, and logs Found project X checked out, undoing checkout or the same for an artefact. Anything unsaved in that checkout is discarded. This is deliberate — the alternative is generation failing because someone left an object open — but it is worth knowing before blaming the user.

Changes made in SharePoint disappeared

That is Default Synchronization Behavior, which defaults to discarding changes made to an uploaded document. It is a deliberate choice for template-driven documents: the copy in SharePoint is a starting point, and edits to it are not meant to flow back.

The Discard Changes After Upload Condition beside it takes precedence, and is evaluated per artefact against the document object template rather than against the document. If some documents keep their changes and others do not, that condition is why.