# Troubleshooting

> What the plugin's messages mean and what to do about each one.

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.

<Callout type="tip">
**Test connection** distinguishes these two deliberately. It calls an endpoint
that needs no scope at all, so it can tell an invalid key apart from a valid
key that is missing permissions.
</Callout>

## 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.

<Callout type="warning">
**Clear cache** removes cached project data from the machine. It then reloads
the project list, so clearing the cache does not leave you with nothing to fall
back on, provided you are online at the time.
</Callout>

## 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.