Table of Contents

Diagnosis and repair: content not displaying

This article provides systematic troubleshooting methods and improvement suggestions for common issues where virtual content fails to display in image tracking, helping developers quickly locate and resolve problems.

Common causes and troubleshooting methods

Content not displaying typically involves image recognition, functional implementation errors, or permission restrictions. Below are the main causes and troubleshooting steps:

Image recognition failure

Symptom: Virtual content does not appear at all after the camera is aimed at the target image.
Troubleshooting methods:

  • Check image recognizability: Use the Target Image Detection Tool to upload the image and confirm the recognizability score (must reach 4~5 stars).
  • Verify image quality: Ensure the image meets the texture, size, and proportion requirements in Best Practices.
  • Check physical target object: Ensure the surface of the physical target object (e.g., poster, card) is non-reflective, flat, and unfolded.
  • Review logs: Check application logs for TargetLoad events to confirm whether the target image loaded successfully.

Improvement suggestions:

  • Optimize images: Increase contrast, avoid repetitive patterns, ensure the subject occupies over 70% of the frame.
  • Replace images: If issues persist after optimization, replace with test images from official Samples (e.g., namecard.jpg) to verify if the problem lies with the image itself.
  • Ensure physical object: Use matte or textured surfaces for physical targets, keeping them flat and unfolded.
  • Check logic: Ensure the application correctly loads the target image used for testing.

Functional implementation error

Symptom: Image is recognized, but virtual content is not displayed or appears in abnormal positions.

Troubleshooting methods:

  • Check ImageTarget configuration:
    • Verify the Source type points to the correct file in the StreamingAssets folder.
    • Ensure Scale is set to the actual physical dimensions.
  • Confirm prefab hierarchy: Virtual content (e.g., Cube) must be a child node of ImageTarget and not disabled.

Improvement suggestions:

  • Reset configuration: Delete and recreate the ImageTarget in the scene, drag the prefab following specifications, and bind the image.
  • Simplify testing: Temporarily remove custom scripts, retain only a basic Cube, and confirm the minimal runnable scene.
  • Check logs: Search for ImageTargetController-related errors, such as fail to load target data.

Permission issues

Symptom: Content disappears after functioning normally for a period.
Troubleshooting methods:
Confirm if you fall under any of the following scenarios:

  • Using on XR headsets
  • Using a custom camera
  • Using AR Engine/ARFoundation on mobile devices

If any of the above apply, you may be using a trial License.

Improvement suggestions:

  • Use a commercial License.

Virtual content issues

Symptom: Content displays normally initially but becomes invisible when the camera is very close to or far from the target object.
Troubleshooting methods:

  • Check near-far clipping settings: Ensure near and far clipping planes for rendering virtual content are within a reasonable range.
  • Check content model size: Excessively large models may cause clipping through when close to the target; overly small models may become invisible when distant.

Improvement suggestions:

  • Set appropriate near and far clipping values.
  • Ensure virtual content has a suitable physical size relative to the target object.

Summary and best practices

Content display issues typically stem from images, implementation, permissions, or the content itself. Recommended troubleshooting sequence:

  1. Check if the License is commercial.
  2. Verify if virtual content is appropriate.
  3. Validate target image quality.
  4. Confirm program implementation or development configuration issues.

If issues persist, provide logs, screen recordings, etc., via the EasyAR official forum or technical support for further analysis.