Mega positioning failure troubleshooting guide

Mega utilizes advanced visual positioning algorithms to achieve high-precision positioning through cloud-based Mega Block retrieval and visual feature matching calculations. In practical use, various factors such as configuration errors, environmental changes, or network fluctuations may lead to positioning failures.

This document aims to help you quickly assess the positioning status, distinguish between "normal waiting" and "abnormal errors," and perform rapid diagnostics based on three major categories: configuration, environment, and service.

Positioning process

You need to collect mapping data in the target area and build a Mega Block, then add the reconstructed Mega Block to the localization library and verify the availability of the localization library.

Within the area covered by the built Mega Block, with good lighting, rich features, and normal network conditions, positioning is usually successful within seconds. Upon successful positioning, the current device's location and orientation in the Mega Block will be returned.

Check localization status

If you use Mega Toolbox to verify the localization result, you can directly check the localization status
If you are a Unity developer and localization fails, you can check the specific information returned by the localization MegaTrackerLocalizationStatus on the screen. If this information is not displayed on the screen, you need to enable diagnostic information.

Possible values of MegaTrackerLocalizationStatus

Constant	Value	Description
UnknownError	0	Unknown error
Found	1	Localized to Block
NotFound	2	Failed to localize to Block
RequestTimeout	3	Request timeout (exceeds 1 minute)
RequestIntervalTooLow	4	Request interval too short
QpsLimitExceeded	5	QPS limit exceeded
WakingUp	6	Service is waking up
MissingSpotVersionId	7	Missing SpotVersionId, possibly not set
ApiTokenExpired	8	API Token expired

Solutions for the above exceptions:

Request timeout: Check and fix the network condition. If necessary, you can increase the request timeout time MegaRequestTimeParameters.Timeout. However, poor network conditions may also affect the tracking performance, so it is necessary to resolve the network issues as much as possible.
Request interval too short: Reduce the request interval.
Connection or transmission failure: Check and fix the network condition.
QPS limit exceeded: Contact EasyAR business personnel for QPS expansion.
Service is waking up: The system is waking up. Please wait for a while and try again.
Missing SpotVersionId: Please configure SpotVersionId.
API Token expired: Regenerate the API Token in the EasyAR management console.

UnknownError usually has two scenarios:

Connection or transmission failure.
Service returns an exception.

For UnknownError, you can obtain detailed information through MegaLocalizationResponse.ErrorMessage.

Common error classification and troubleshooting

Based on the status and symptoms returned by the positioning, common issues can be divided into the following three categories: configuration issues, environmental factors, and the service itself.

Configuration issues

This type of issue usually occurs during the development integration phase, manifesting as the service being completely unable to start.

If you encounter License, Invalid Key, or similar issues in logs or on-screen prompts during development or testing, possible causes include: AppID/BundleID mismatch, expired license, or incompatible subscription plan. Please refer to the table below to check your license settings.

Error	Solution
Invalid Key: No matched Bundle ID	Bundle ID does not match the license key. Modify either one to make them match.
Invalid Key: No matched Package Name	Bundle ID does not match the license key. Modify either one to make them match.
Invalid Key: License does not apply to current variant	Using an enterprise SDK with a non-enterprise license key, or vice versa.
Invalid Key: License for an old version does not apply	The license version is too old. Create a new license.
Invalid Key: Invalid format	The license format is incorrect, e.g., incomplete copying.
Invalid Key: Server verification failed	The license has been deleted or lacks device usage permissions. For headset usage, contact sales to add permissions.
License does not apply to eyewear	The license cannot be used on headsets. Switch to an XR license.
License is expired	The license has expired.

Additionally, note that trial licenses have certain limitations. Upgrading to paid versions of EasyAR Sense or paid EasyAR Mega services can resolve this. If you are already using the paid version of EasyAR Sense, you can ignore or remove the relevant text from the sample.

Camera display abnormality

During the development or testing of EasyAR Mega applications, if you encounter issues such as black screens, crashes, or no camera display, please follow the steps below to systematically troubleshoot and collect information.

Try to resolve the issue yourself

If you are using Unity for development or testing, ensure that you have enabled diagnostic information by checking the Diagnostics Controller (Script) in the AR Session (EasyAR) -> Inspector.
Check the content displayed on the screen or in the logs to see if there are any clear text prompts on the UI.
In most cases, error messages are self-explanatory. If the screen or logs indicate the cause of the error, you can address it accordingly. For example: cameraDevice.openWithPreferredType fail (you need to check if the camera is available).
If the message indicates "not supported" (e.g., the device does not support ARCore or other features), this is a normal limitation and does not require further troubleshooting.

Unable to resolve the issue yourself

Please first attempt to resolve the issue based on the available information. If you are unable to resolve it yourself, to help EasyAR staff quickly identify the problem, please provide detailed, reproducible technical information. Avoid describing only the phenomenon, such as "black screen." It is recommended to include the following in your feedback:

Complete logs: Unity or Sense logs
Screenshots or screen recordings: Full screen during the black screen. If there is diagnostic information, ensure it is visible and captured in the screenshot.
Detailed device information: Device model (e.g., iPhone 15, HUAWEI P40), system version (e.g., iOS 17.1, Android 14), EasyAR Sense version, EasyAR Sense Unity Plugin version, Unity version, etc.

Not running on-site, continuously NotFound

Developers test using simulators or screen recordings in the office but cannot locate the issue. The possible reason is that the MegaLocationInputMode is set to Onsite, but it's not running on-site. The correct mode should be selected during development based on the Mega location input mode:

Constant	Value	Description
Onsite	0	Input mode for on-site usage, where location data is typically obtained from the device and fed into Mega, usually handled internally by FrameFilter
Simulator	1	Input mode for remote usage, where location data needs to be simulated as on-site data and fed into Mega through the corresponding interface (optional)
FramePlayer	2	Input mode when using `FramePlayer`. This mode is read-only

Environmental factors cause

This type of issue manifests as the service functioning normally, but the location consistently returns NotFound.

Continuously not found when facing white walls or floors

When the camera view consists of large areas of white walls, glass, or monochromatic floors, the status will continuously return "NotFound."

Reason: Visual positioning relies on texture features. Weak-texture areas cannot extract feature points.

Solution: This is normal behavior. Move the camera toward areas with rich textures to initiate.

On site and texture-rich, but persistently not found

On site, facing a textured area, but unable to successfully locate for an extended period.

Possible causes:

Scene changes: The on-site environment (e.g., renovations, poster replacements, drastic lighting changes) differs significantly from the scene during mapping.
Coverage not captured: The user's standing position exceeds the coverage area of the original mapping.

Solutions:

Move to the area covered during the original mapping and try again.
If the scene has undergone permanent and significant changes, re-capture and update the Block.

Caused by the service itself

Just added block, continuously waking up

When you have just configured the positioning library or just started the positioning library, the service status shows WakingUp or remains NotFound for a long time. This is because the Mega service has a cold-start mechanism, and the first load requires waking up from cold storage. Keep the network unobstructed and wait 10-30 seconds before retrying.

Service returns exception

Https status	Status code	Reason
200	21	QPS limit exceeded
200	1040 x	Incorrect parameters, library, or map data, see specific message description
200	4000 x	Algorithm-level error, see specific description
401	-	Authentication failed, see specific message description
404	-	Incorrect path in URL
50x	-	Server program error

Solutions for service exceptions:

QPS limit exceeded: Contact EasyAR business team for QPS expansion
Authentication failed: Resolve according to the specific message description, common issues include device time deviation from standard time being too large, API Key lacking CLS permissions, etc.
Other cases: Please report to EasyAR staff for resolution

Issue feedback

If the problem persists after the above troubleshooting steps, please follow the steps below to collect information and report it to the EasyAR technical support team.

Export `Mega localization service` information

Log in to your account in Unity's Mega Studio, select the localization library with positioning anomalies, and locate the export button for Mega localization service in the image below. The exported file should be in the format MegaStudio_ServiceInfo_username_YY-MM-DD_HH-MM-SS.json. The Mega localization service only contains Mega Block and localization library information, excluding other sensitive data.

Export Mega localization service information

Record EIF files

If you encounter issues during mobile testing, please use Toolbox to record mobile EIF files

If you encounter issues during glasses testing, please use Toolbox to record glasses EIF files

If you encounter issues in your own application, you can record EIF files using your application

When using WeChat Mini Programs, you can record EIF files for Mini Programs

Record the issue phenomenon using devices such as mobile phones and glasses

In the field of AR, textual descriptions often fail to convey accurate information, and interpretations can vary widely among individuals. At the same time, runtime screen recordings are highly valuable as they help establish a shared understanding between you and EasyAR staff. You can use the built-in functions of devices like mobile phones and glasses or rely on third-party software for recording. It's important to note that screen recording may impact runtime performance, potentially affecting tracking effectiveness and overall performance.

Note

Before recording, it is recommended to refer to the corresponding Sample during runtime and display necessary debug information on the screen. Along with the recording, you should also provide the corresponding EIF data captured during the recording session.

Unity development issue feedback

If you encounter any abnormal issues during Unity development, you should check whether you have completed the following 4 steps one by one.

Have tried the latest version of the EasyAR Sense Unity Plugin. New versions usually include bug fixes and new features. It is recommended to upgrade to the latest version first.
Have read the EasyAR development documentation and Mega Guide. The documentation usually contains some explanations for specific situations.
Have checked the system and Unity logs. It is recommended to provide complete logs when asking questions.
Have tried to reproduce the issue in an empty Unity project or in the Sample.

If you have completed the above 4 checks and still cannot resolve your issue, you can follow the process below in the EasyAR Sense Unity Plugin to provide complete information for EasyAR technical staff to analyze and solve your problem.

In Unity -> EasyAR -> Sense, select Ask a Question
In Ask a Question, you need to provide the following information:
- Select the problematic runtime environment. Only a single environment can be selected.
- Copy the device information. In EasyAR Session, set DiagnosticsController.DumpSession to Log, copy one frame of the output, and fill in the result below.
- Select all EasyAR features you used when the problem occurred. Multiple selections are supported.
- Confirm that you have completed the above 4 checks. It is recommended to describe how to reproduce the issue in the Sample when asking the question.
- Click the copy function in the upper right corner.
  
  When you first open the Ask a Question window, the information below may not be fully displayed. You need to select the environment and features you used before it will be displayed.
Click Go to EasyAR Q&A below to submit the copied information to EasyAR official, or directly provide feedback to EasyAR staff.