PF Forms Runtime Troubleshooting

ProcessFactorial Forms may encounter errors at runtime. This article explains how those errors appear to the user and how to resolve common issues.

How errors appear

Runtime errors are not displayed on the form itself. Instead, they appear in one of the following ways:

Channel	What you'll see
Bootstrap alert banner	A coloured bar at the top or bottom of the page with an error message and a close button. If the server returned additional details, they are shown below the main message.
Browser console	Technical errors and warnings are logged to the browser developer tools console (`F12` → Console tab). Check here if no banner appears but the form is not rendering.
Blank or partial form	The form may fail silently during initialisation. The page is blank or only a loading spinner is visible. Check the browser console and network tab for details.

Bootstrap alert banners use colours to indicate severity: red for errors, yellow for warnings, and green for success.

Authentication and token errors

`Authenticated forms require the parent web app to expose window.pfGetJWTToken`

What you see: A red alert banner and a JavaScript error in the console. The form does not render.

Cause: The form requires authentication but the parent application has not provided window.pfGetJWTToken.

Resolution: Define window.pfGetJWTToken as an async function that returns a valid JWT token. See Parent App Integration.

Form loads but API calls fail with 401

What you see: A red alert banner with a message such as "Record does not exist or you do not have access to it". The form may render partially but cannot load or save data.

Cause: The JWT token returned by window.pfGetJWTToken is expired, invalid, or has the wrong audience or scopes.

Resolution: - Verify the token is being acquired successfully (check your auth provider). - Ensure the token's audience and scopes match what the PF Forms API expects. - Check that the token has not expired.

Snippet and initialisation errors

`Error fetching form content`

What you see: A red alert banner with this message. The form does not render.

Cause: The Forms Engine could not load the form definition from the API. The server response may include additional details below the main message. Common underlying causes include:

Anonymous form mismatch. Snippet must be redeployed when changing the anonymous status of a Form. The form was switched between anonymous and authenticated after the snippet was generated. Re-export the snippet from the configuration portal and update the page.
Unable to find Published DEMForm with Id The form has not been deployed to this environment. Deploy the form from the configuration portal.
Access to this form not supported from {url} The form snippet is locked to specific allowed host URLs, and the current page URL does not match. Re-export the snippet for the correct host URL, or update the allowed host URLs in the configuration portal.
DEM form not found The form token in the snippet is invalid or the form has been deleted. Re-export the snippet from the configuration portal.

Resolution: Check the additional detail below the alert message for the exact cause, then follow the guidance above.

`Missing data-base-url on .npoform`

What you see: A JavaScript error in the browser console. The form does not render.

Cause: The form snippet container is missing the required data-base-url attribute.

Resolution: Re-export the snippet from the configuration portal — it will include the correct attributes. Do not manually edit the snippet HTML.

Data access errors

`Record does not exist or you do not have access to it`

What you see: A red alert banner. The form renders but cannot load existing data.

Cause: Either the record identifier is invalid, or the current user's JWT token does not grant access to that record.

Resolution: - Verify the record identifier is correct. - Confirm the user has the necessary permissions in the external identity provider.

`Please enter data before saving a new record`

What you see: A yellow warning banner.

Cause: The user clicked Save or Submit on a new record with no data entered.

Resolution: Enter data in at least one form field before saving.

Document upload errors

`File type '...' is not allowed`

What you see: An error message below the file upload control.

Cause: The selected file type is not in the list of allowed file types configured on the form.

Resolution: Choose a file with an allowed extension, or ask the form designer to update the allowed file types in the configuration portal.

`File size exceeds maximum allowed size`

What you see: An error message below the file upload control.

Cause: The selected file is larger than the maximum file size configured on the form.

Resolution: Choose a smaller file, or ask the form designer to increase the maximum file size in the configuration portal.

`There was an error uploading the document. Please try again.`

What you see: An error message below the file upload control.

Cause: A network or server error occurred during upload. This may be temporary.

Resolution: Try uploading the file again. If the problem persists, check the browser console for more details.

General errors

`Error saving data`

What you see: A red alert banner after clicking Save or Submit.

Cause: The server rejected the save request. This could be due to validation errors, a network issue, or a server-side problem.

Resolution: - Check the browser console and network tab for the server response. - Ensure all required fields are filled in. - Try saving again. If the problem persists, contact support.

Events never arrive in the parent listener

What you see: The parent application does not receive postMessage host events when the user interacts with the form.

Cause: The parent window has not registered a message event listener, or the listener is filtering out the events.

Resolution: - Register window.addEventListener('message', ...) in the parent window. - Check that your listener accepts events with type: 'processfactorial:host-event'. - If the form is in an iframe, ensure the listener is on the parent window, not the iframe.

Getting more information

If an error occurs and the alert banner does not provide enough detail:

Open the browser developer tools (F12).
Go to the Console tab — the Forms Engine logs detailed error information here.
Go to the Network tab and look for failed requests to the PF Forms API. The response body contains a JSON object with the error details:
```
{
    "message": "Summary of the error",
    "errors": ["Detailed error information"],
    "warnings": []
}
```

If you cannot resolve the issue using the guidance above, contact ProcessFactorial Support with: - The exact error message from the alert banner or console - Any additional detail shown below the alert message - The URL of the page where the error occurred