Troubleshooting
Diagnose loading, renderer, and geographic placement problems.
Check the pipeline in order: project conversion, manifest, queried features, renderer registration, then visual placement. This separates content problems from SDK or geospatial setup problems.
The project manifest returns 404
Use the complete public key from the project's Keys tab, including pk_.
The project ID in a dashboard URL is not the SDK key.
Confirm the API hostname. Current SDKs use https://api.realityimport.com. If an
older checkout still uses test-reality-import.miceo.me, update the SDK. The
hostname fix is in Lens Studio commit dfa7843 and Unity commit def2ada.
The project manifest returns 409
At least one layer is not ready or has no generated FlatGeobuf output. Inspect all project layers, including those outside your current query area.
| Layer state | Meaning |
|---|---|
uploading | The source upload has not completed |
queued | Conversion is waiting to run |
converting | The worker is processing the source |
ready | Generated data is available |
failed | Conversion failed; inspect the layer error |
Changing render mappings or model placement can put a previously ready project back into a pending state. Wait for conversion before reloading the SDK.
The SDK reports a missing renderer
Compare each manifest render-definition key with the renderer's identifier:
- Lens Studio:
definitionName - Unity:
DefinitionName
Matching is case-sensitive. Both managers require a registered renderer for every definition in the manifest, including definitions not used by nearby features.
For a model, add a model renderer; a generic point marker is not a replacement. For a dataset, verify that its mapped definition matches the renderer you added.
The Lens Studio supplied point marker uses birds, not marker. The built-in
model path uses the exact identifier model. Unity includes a renderer base
class and template, but no built-in model or dataset renderers.
The renderer exists but rejects the feature
The project definition, feature geometry, and renderer implementation must agree.
Do not map MultiLineString features to code that only handles LineString.
The supplied Lens LineRenderer currently declares multipart support but rejects
MultiLineString in its implementation. Split the source into single lines or
supply a multipart renderer. In Unity, implement every type declared in Types.
The project loads but nothing appears
- Check the manager's actual query radius in the Inspector.
- Check the geographic reference or location override against the content.
- For models, check the anchor point—not the model mesh's visible extent.
- Confirm the renderer was invoked and has its required prefab/material assets.
- Check longitude/latitude order and coordinate units.
- Reload after changing content. Lens Studio loads once at startup; Unity reloads
when
Refresh()is called or editor preview refreshes.
A bounding-box query can legitimately return no features. Increasing a radius will not fix an incorrect location or coordinate reference system.
Content is misplaced or at the wrong scale
Use the SDK's geographic helpers instead of treating longitude and latitude as engine positions.
| SDK | Local units | Horizontal axes |
|---|---|---|
| Lens Studio | Centimeters | X east, negative Z north |
| Unity | Meters | X east, positive Z north |
For a dataset, check its source CRS and column mapping. For a GLB, also check the model's original units, placement scale, and renderer-specific rotation conversion. Do not apply a meters-to-centimeters conversion twice.
The current Lens model renderer forces world Y to -200 cm, and the dataset render root has a -140 cm offset. Lens geographic helpers do not apply geographic altitude. These are renderer/placement limitations, not evidence that uploaded coordinates are wrong.
Lens Studio waits for GPS
Check location permission, account pairing, connectivity, and the LocationManager references. A pinned location still waits for real location-service initialization. Follow Snap's location requirements.
If heading alignment is disabled, movement alone will not enable it. Inspect Update Heading and any manual offsets in the scene.
Unity waits for a geospatial reference
The ARCore adapter waits for Earth tracking. Verify AR Foundation, ARCore Extensions, the Earth/Anchor Manager references, Google API configuration, and required device permissions.
Test Google's Geospatial sample independently. A successful Reality Import web request does not prove that the ARCore geospatial session is ready.
For Edit Mode, assign a Creator Origin and verify Cesium terrain setup. Runtime location overrides do not replace the Creator Origin used by editor preview.
Models fail to load after the manifest succeeds
The GLB is a separate request from the manifest and FlatGeobuf data. Inspect the
returned asset_uri, network access, and the renderer's asset-loader error.
In Unity, ensure a GLB loader is installed and configured for the render pipeline. In Lens Studio, retain the SDK's remote-media dependencies and GLB material asset.
HTTPS fails before a response arrives
A TLS certificate error happens before the manifest can be processed. Use an API and asset host with a trusted certificate valid for its hostname. Do not disable certificate verification as an SDK fix.
The current SDKs target the production API. A project key alone does not switch them to a staging server.