Handling Missing References in Imports
Liferay DXP 2025.Q3
When importing content, page, or user-related data (such as categories, tags, vocabularies, fragments, master pages, layout page template collections, widgets, parent pages, roles, organizations, accounts, and account groups), Liferay manages references to entities missing in the target environment in several ways:
- Creates an incomplete placeholder entity
- Keeps the reference but shows a UI warning or 404
- Ignores the missing field
- Defaults to a known fallback (for example, using the importing user as author)
The following sections describe how Liferay applies these behaviors to different entity types.
Handling Missing Content References
| Referenced Entity | Import Behavior |
|---|---|
| Categories | Creates a placeholder category in Incomplete status. If the vocabulary exists, it’s associated. |
| Tags | Automatically created with no special status. |
| Vocabularies | Creates a placeholder vocabulary in Incomplete status. |
Handling Missing Page References
When a referenced page-related entity is missing, Liferay either keeps the reference or creates a placeholder in EMPTY status. Page placeholders differ from taxonomy/user placeholders: they are not “incomplete” entities requiring user review, but structural stand-ins to preserve page hierarchies and layout relationships.
| Referenced Entity | Import Behavior |
|---|---|
| Fragments | Keeps the reference and indicates in the UI that the fragment is not present. |
| Master Pages | Creates a dummy Master Page in EMPTY status. |
| Widgets | Keeps the reference and marks the widget as missing in the UI. |
| Pages (Parent Pages) | Creates a dummy parent page in EMPTY status to preserve the hierarchy. |
| Layout Page Template Collections | Creates a dummy collection in EMPTY status. |
| Other Lazy Page Entities | Lazy-loaded page entities missing during import have EMPTY status. |
Handling Missing User References
| Referenced Entity | Import Behavior |
|---|---|
| Roles | Creates a placeholder role in Incomplete status. |
| Accounts | Creates a placeholder account in Incomplete status. |
| Account Groups | Creates a placeholder account group in Incomplete status. |
| Organizations | Creates a placeholder organization in Incomplete status. |
Understanding the Incomplete Status
Entities created as placeholders are marked with the Incomplete status. These entities
- Act as functional placeholders
- Are excluded from validation-dependent features
- May show warnings or tooltips in the UI
- Must be reviewed and updated manually
You can view and manage these entities by filtering for Incomplete status in the relevant app (e.g., Categories, Users).
Understanding the EMPTY Status for Page Entities
Page-related placeholder entities (such as parent pages, master pages, layout collections, and other lazy page elements) use the EMPTY status. These entities
- Preserve hierarchy and layout relationships during import
- Do not represent partially created entities
- Provide a structural placeholder instead of missing references
- Are visible in Page Management with their
EMPTYindicator
They can be replaced or configured after import if needed.
Entities in EMPTY status appear only in administrative applications (for example, Pages, Users, or Roles). They do not appear in end user or non-admin experiences, including navigation, the Item Selector, or other user-facing tools.
Best Practices
Follow these guidelines to maintain data integrity and ensure a smooth import process:
-
Review imported data for
Incompleteentities after import. -
Use consistent environments between source and target to reduce missing reference scenarios.
-
Audit content regularly to ensure taxonomy, user assignments, and layout references are intact.