Troubleshooting

The plugin tries to name the thing you can actually change. This is what each message means.

Keys and connecting#

"That does not look like a GIMLabs API key." Keys begin with gim_live_ or gim_test_. The dialog checks the shape before storing anything, so nothing has been saved. Copy the key again from Settings > API keys in GIMLabs, taking care not to pick up surrounding whitespace.

"No API key set. Open Settings and add one." The plugin has no credential. Go to Web > GIMLabs for QGIS > Settings and add one.

"A key is stored, but the auth database is locked." QGIS needs its master password before it can read the credential. You are prompted once per session. If you dismissed the prompt, restart QGIS and enter it.

"A key was stored but is no longer in the auth database." The credential has been removed from QGIS, usually by clearing the authentication database or moving to a different profile. Add the key again. If you no longer have it, revoke it in GIMLabs and create a new one.

"This key is not valid." The key has been revoked, or it was mistyped. Check under Settings > API keys in GIMLabs that it is still Active, and create a replacement if not.

"This key cannot read projects." The key is genuine but has no Projects scope. Keys cannot be edited after creation, so create a new one with the right scopes and revoke the old one.

Scopes and missing layers#

"Needs the map:read scope on your API key." Site boundaries, location groups and marker artwork all sit behind the Map scope. A key without it loads locations and nothing else. Create a new key with Map ticked.

"Site boundary: none drawn for this project." The scope is fine and the request worked; there simply is no boundary on that project. Draw one in Manage and refresh.

"Location groups: none defined for this project." Same thing for groups.

"Nothing ticked to load." Choose at least one layer before loading.

Projects#

"No projects on this API key." The key is restricted to named projects and none of them are visible, or the account genuinely has no projects. Check the key's project restriction in GIMLabs.

"No projects match your search." The search runs on the server against project reference and name, so it looks past the 100 most recent that are listed. If you expect a match, check the spelling of the reference.

Offline and cache#

"Offline. Showing the list cached ..." The plugin could not reach the API and fell back to what it had. The message leads with how old the cached copy is. Everything on screen is from that point in time.

Only a network failure falls back to the cache. A permissions error or a missing project is a real answer and is shown as one, rather than being papered over with stale data.

Cached responses expire after 7 days. If you have been offline longer than that, you will need a connection before the project will load again.

Coordinates and the map#

Boreholes plot in the wrong place, or in the sea. Check Grid for easting/northing on the load dialog. It defaults to EPSG:27700, British National Grid. If the project's surveyed coordinates are in a different grid, the points will land a long way from where they belong.

Some locations are missing from the layer. The load summary counts locations that could not be placed. A location needs either surveyed coordinates or a map placement in Manage; one with neither cannot be drawn.

QGIS asks to download the OSTN15 grid file. You do not need it, and this should not normally appear. The plugin permits the fallback transform, which is accurate to roughly 2m against OSTN15's 1m, and that is smaller than the symbol you are plotting. Install it if you want and QGIS will use it automatically.

Updates#

New versions do not appear in the plugin manager. The update repository is registered when a key is saved. If the plugin was installed but a key was never added, or Forget stored key was used, there is no repository to poll. Add a key again and the entry is recreated.

Registration is best-effort, so a plugin that could not register still works, it just will not update itself. You can always install a newer zip over the top from the GIMLabs dashboard.

Rate limits#

The API is rate limited per key and per company. The plugin fetches one page of projects rather than all of them precisely to stay well inside those limits. If you are hitting them, it is usually several people sharing one key on a large estate; create a key per machine, or restrict keys to the projects they are for.

Still stuck#

Check the QGIS log for detail the dialog does not show: View > Panels > Log Messages. Then contact support@gimlabs.io with what the log says.