Table of Contents

Troubleshooting: content not displayed/activated

When using image cloud recognition, you may encounter a problem where virtual content cannot be displayed or activated. This article provides a systematic troubleshooting method. Note that in most cases, the reasons for image cloud recognition failure are exactly the same as those for local recognition failure. You can refer to the Troubleshooting section for planar image tracking. This section only adds issues and solutions specific to cloud recognition.

Common causes and troubleshooting methods

Network connection issues

Symptom: No response after a recognition request is sent, or an error code is returned.
Troubleshooting methods:

  • Check whether the device is connected to the network (Wi-Fi/4G/5G), and try opening a web page to verify it.
  • Check whether the app has network permission enabled.
  • Capture network error logs in code.
  • Test CRS API connectivity in a browser (reference: Health check | GET /ping).

Improvement suggestions:

  • Add network status detection in the app and show prompts when the network is weak.
  • Set request timeout, then retry or downgrade to local tracking.

Service configuration errors

Symptom: The recognition request is rejected and returns Unauthorized or Invalid Key.
Troubleshooting methods:

  • Check whether the CRS API Key and Secret filled in the code are correct.
  • Check that the Client-end URL filled in the code is not wrong (for example, mistakenly entered as the Server-end URL).
  • Confirm that the License Key is activated and has not expired (check it in the account center on the EasyAR official website).

Improvement suggestions:

  • Use the Copy button in the CRS image library to copy your related service configuration and ensure it is filled in correctly.

Target library/application configuration errors

Symptom: A target image was recognized correctly before, but the recognition request now fails.
Troubleshooting methods:

  • Get the target status through the CRS API and confirm that the target image is in the "activated" state ("active":"1").
  • Check whether the target ID is exactly the same as the one in the code (case-sensitive).

Improvement suggestions:

  • When the cloud image library is updated/changed, ensure that the specific targets used by the app are always activated.
  • Carefully review the code.

Local loading failure in hybrid mode

Symptom: Cloud recognition succeeds, but local tracking does not start and the content is not displayed.
Troubleshooting methods:

  • Confirm that no exception is thrown when the local ImageTarget is loaded (check the logs).
  • Verify whether ImageTracker is enabled.

Improvement suggestions:

  • Wrap the local loading logic with try-catch, capture exceptions, and retry.
  • Ensure that the virtual content is a child object of ImageTarget and is not disabled.

Summary and best practices

Issues where cloud recognition content is not displayed are mainly concentrated in three aspects: network, service configuration, and target status. In hybrid mode, you also need to pay attention to local loading. It is recommended to troubleshoot in the following order:

  1. Check the network connection and confirm CRS service connectivity;
  2. Check service settings such as License, API Key/Secret, and Client-end URL.
  3. Check the status of the target image in the CRS image library and ensure that the image library is consistent with the target ID in the app;

If the issue is complex, enable EasyAR debug logs or contact technical support.