[Content Import]: Misleading Errors for Image Fields

[rjvelazco]

Problem Statement

When importing content with image fields, invalid paths, such as non-existent files or URLs with query parameters, result in a misleading error code: RELATIONSHIP_VALIDATION_ERROR.

The code RELATIONSHIP_VALIDATION_ERROR gives the impression that it is a relationship field, but there is something wrong with the image path.

Steps to Reproduce

[!IMPORTANT] To reproduce these issues, it's important that the image you are trying to import in a contentlet, exist in dotCMS

non-existent path

Attempt to import an image with a non-existent path and see how we get this RELATIONSHIP_VALIDATION_ERROR error message instead of the error leading to IMAGES.

CSV

title,image
Image,"/fake/path/to/image.jpeg"

RESULT

{
    "code": "RELATIONSHIP_VALIDATION_ERROR",
    "field": "required: image\n",
    "message": "Contentlet with ID 'Unknown/New' ['Image'] has invalid/missing field(s). - Fields: [REQUIRED]: Image (image)",
    "row": 2
}

System doesn't support Query Params

Attempt to import an image with query params in the path and see how we get this RELATIONSHIP_VALIDATION_ERROR error message instead of the error leading to IMAGES.

CSV

title,image
Image,"${YOUR_IMAGE_PATH}?language_id=1"

RESULT: Same misleading error as above.

Acceptance Criteria

• [ ] Errors caused by invalid image paths or query params must use a more specific error code, e.g., IMAGE_VALIDATION_ERROR.
• [ ] The error message should explicitly mention the image path and reason for failure (e.g., “Image not found”, “Query params not supported”)
• [ ] Do not use RELATIONSHIP_VALIDATION_ERROR for image fields unless the image field is part of a true relationship.
• [ ] Ensure that documentation notes the current limitation: image paths must not include query params (if not fixed).

dotCMS Version

main/trunk

Proposed Objective

User Experience

Proposed Priority

Priority 2 - Important

[github-actions[bot]]

PRs:

• https://github.com/dotCMS/core/pull/32204
• https://github.com/dotCMS/core/pull/32335
• https://github.com/dotCMS/core/pull/32409

[rjvelazco]

Failed QA

• Docker image: [dotcms/dotcms:trunk_cd29a31]

Case 1: No warning for invalid image path when the field is not required

Steps to reproduce:

1. Create a contentlet with an image field (leave it as not required).
2. Use the Import API with an invalid image path.
3. Observe that the contentlet is created successfully, but no warning is shown to the user about the invalid image path.

Expected: A warning should be shown to inform the user that the image path is invalid, even if the field isn’t required.

https://github.com/user-attachments/assets/18ae3a14-4edc-436d-aec3-14b296a588a8

Case 2: Improved error message, but still unclear and unhelpful

Steps to reproduce:

1. Create a contentlet with a required image field.
2. Use the Import API with an invalid image path.
3. Observe the error message:

Issue: The error mentions a missing/invalid field, but it doesn't explain why the field is invalid or provide a link to the official dotCMS documentation for importing images.

Expected: A clearer message that explains the specific problem (e.g., "invalid image path") and ideally links to the docs for guidance.

https://github.com/user-attachments/assets/578c7e36-48c8-451a-9fca-46d0a41a6a3d

[fabrizzio-dotCMS]

Note to QA: We need to test that we can use existing files to import into fields of type image and file Here's an example:

1. title,image
2. Image,"/fake/path/to/image.jpeg"
3. diving,"/images/diving.jpg"
4. YellowRedline,"https://s3.amazonaws.com/uploads.bmxmuseum.com/user-5 images/22838/img_87765745130d27601794c97b.jpg"
5. Eddie,"/images/gallery/beach/iron-maiden-live-after-death.gif"

In this example: Line number 1 has the column descriptions Line number 2 has an error that should be reported, causing the import of this content to fail Line number 3 is meant to use an existing image in the existing content we're creating (if the image does not exist locally, it should also fail) Line number 4 uses an external URL (this should succeed unless there's an error downloading the image)

⚠️ binary fields only support url, they don't support paths to existing files ⚠️

[rjvelazco]

Failed QA

• Docker image: [dotcms/dotcms:trunk_a91f6d1]

If you pass an invalid image, the message is Invalid internal file path, which is better than the last one but still missing information. It can be like: The provided path does not point to a valid dotCMS Image Asset. Please make sure the path is correct

External Image URL Misleading message

If the job fails to import an External URL, the error message says: "Invalid Internal File Path"

Steps to reproduce:

1. Create a contentlet with an image field Required.
2. Use the Import API with an invalid URL image path. I used: https://s3.amazonaws.com/uploads.bmxmuseum.com/user-5 images/22838/img_87765745130d27601794c97b.jpg
3. See the error.

https://github.com/user-attachments/assets/7886385a-809a-464e-8a7d-761fe0134ba2

[valentinogiardino]

Note to QA:

Please also try to reproduce and notify about "Test Case 2: Image Path Validation (Fails to Stop)" described on this ticket: #32416 The fix applied in this ticket (#32031) may have resolved that issue as well.

If #32416 issue is still reproducible, do not fail QA on this ticket — we will continue addressing it under the original ticket.

[fabrizzio-dotCMS]

Needs Doc Notes:

Content Import: Binary vs File Fields - Enhancement Documentation

Overview

This document outlines the improvements made to Content Import functionality, specifically addressing the handling of Binary and File field types (Image and File) and their support for external URLs versus internal dotCMS paths.

Field Types Covered

• Binary Fields: Binary content fields
• File Fields: File and Image field types

---

Previous Behavior

Binary Fields

• Supported: External URLs only
• Limitation: No support for internal dotCMS paths
• Import Method: Direct URL import exclusively

File Fields (Image and File)

• Supported: Internal dotCMS paths only (format: /folder/asset)
• Limitation: No support for external URLs
• Scope: Referenced existing assets within dotCMS only
• Host Dependency: Operated on current host context

---

Current Enhanced Behavior

Binary Fields

• Unchanged: Continues to support external URLs
• Functionality: No modifications to existing behavior

File Fields (Image and File)

• Enhanced: Now supports both internal paths AND external URLs
• Backward Compatible: Existing path functionality preserved
• New Capability: Automatic File Asset creation from URLs

---

New File Field Functionality

URL Processing Workflow

1. Detection: System identifies external URLs in File/Image fields
2. Asset Creation: Automatically generates corresponding File Asset
3. Reference Assignment: Field points to the newly created File Asset
4. Location: Assets are created in the root folder of the currently selected site

Intelligent Import Features

• Deduplication: Repeated URLs are imported only once per import session
• Existence Validation: Files with matching names locally are not reimported
• Session Context: Content Import operations depend on the currently selected site in session

Error Handling Improvements

• Enhanced Messaging: More descriptive and actionable error messages
• URL Validation: Improved validation for both syntax and accessibility
• Path Verification: Better handling of internal path validation

---

Technical Considerations

Site Context Dependency

• Critical: Content Import functionality is tied to the currently selected site in user session
• Import Location: All imported assets are placed in the root folder of the active site
• Session Requirement: Valid site selection must be maintained throughout import process

Backward Compatibility

• Full Compatibility: All existing path-based imports continue to function unchanged
• Migration: No action required for existing content or import configurations
• Validation: Enhanced validation maintains strict standards while expanding capabilities

Implementation Notes

This enhancement maintains full backward compatibility while significantly expanding the capabilities of File field imports. The implementation prioritizes data integrity, user experience, and operational efficiency without disrupting existing workflows.

[rjvelazco]

Passed QA

• Docker Image: [dotcms/dotcms:trunk_fbf27f7]

Videos

https://github.com/user-attachments/assets/1b364e6b-faa7-4683-91ca-dff2f1aafd2f

https://github.com/user-attachments/assets/af5833e8-d099-4c76-a26d-2ad9e6c069df