The exception queue

Assignment Exceptions is where every record that could not be assigned ends up, with the reason and what to do about it.

It is a work queue, not an error log. Rows are meant to be worked and closed. It will not empty itself: an open row is never deleted, at any age, because a queue that quietly empties looks like a problem that went away.

How to work it

The useful first move is to filter by where the fix lives, because that decides who fixes it:

"Show me everything I can fix without leaving Salesforce" is the Monday-morning question, and that is the first three rows.

The categories

Fix lives in the record

No geocode

The record has no billing latitude and longitude, so there was no point to test.

Do: add or correct the billing address so Salesforce can geocode it.

✅ Assignment restarts by itself the moment coordinates arrive. No re-run needed.

A lot of these at once usually means clean rules are off org-wide — check that first.

Imprecise geocode

The address matched only to a city, county or postcode centroid. The record WAS assigned — but from a guessed position, and near a boundary a guess can be on the wrong side.

Do: check the address for a missing street or unit number. If the territory is right, resolve the row.

⚠️ This one does not block anything. It is a note about address quality. Coarse geocodes assigned before this feature existed too; making it a hard stop would un-assign records that are assigned today.

Fix lives in the territory model

Outside every territory

The record geocoded fine and its point falls inside no territory in the model. Nothing is wrong with this record.

Do: open Coverage gaps to see how many records share each uncovered area, extend or add a territory, then select the rows and choose Re-run after a fix. See Coverage gaps.

⚠️ Editing a boundary does not re-assign anything by itself. That is exactly why Re-run after a fix exists — without it you could redraw a boundary perfectly and watch nothing happen.

Fix lives in Salesforce Setup

Callout credential not configured

The GIS credential has not been set up in this org, so the callout was refused before it could do anything.

This is the state every new installation starts in. A queue full of these on day one is expected.

Do: Setup → Named Credentials → KoopGIS. Set the authorisation value, then grant users access to the external credential — two steps, and the second is the one people miss (Admin setup). Then Re-run after a fix.

Governor limit exceeded

The batch hit a Salesforce limit and stopped. The record is fine.

Do: nothing. Retried automatically in a smaller batch. If it keeps happening, something else in the org is consuming the same limit.

Assignment could not be saved

The territory was found, but Salesforce refused to save the association — a validation rule, a sharing restriction, or a territory rule blocking the combination.

Do: read the reason, which carries Salesforce's own message, and clear whatever blocked it. Retried automatically, so a fix is picked up without further action.

Fix lives in the GIS service

Orphan territory model

The service returned territories from a model this org no longer has — its boundaries are held for a model that was deleted here.

🔴 Do not redraw anything. The boundaries are correct. The service is holding a stale copy of a deleted model.

Do: contact MapKraken Labs to reconcile the service against your org, then Re-run after a fix.

This is never a coverage gap, and the distinction matters more than it sounds. A coverage gap is a defect in your map. An orphan model is a defect in the service, where the boundaries are already right. Treating the second as the first sends you to redraw a map that is correct. The product keeps them apart deliberately, and a test fails if it ever stops doing so.

Malformed intersection entry

One entry in an otherwise valid response was unreadable and was skipped. The record may be assigned to some of its territories and not all.

Do: check the record's assignments against the map. Re-run if any are missing; resolve if complete.

Malformed response

The service answered but the body was not readable.

Do: nothing at first — retried automatically. If rows keep arriving, the reason text holds the unparseable response; send it to MapKraken Labs.

Endpoint unreachable

The callout did not connect: DNS, TLS, or the service being down.

Do: nothing at first — retried automatically. Still failing hours later means checking that the KoopGIS credential's URL resolves and the service is running.

Timeout

The service did not answer in time. Reachable but slow.

Do: nothing — retried automatically. A steady stream means the service needs capacity, not that your records are wrong.

Service rejected the request

The service answered and refused. The reason text holds what it said.

Do: read the reason. Retried automatically; if every attempt is refused identically, that message is what MapKraken Labs needs.

Retrying

Six categories retry themselves: endpoint unreachable, timeout, malformed response, service rejected, governor limit exceeded, and assignment could not be saved. An hourly job picks them up on a backoff — 5 minutes, then 10, 20, 40, 80, capped at 4 hours, for up to five attempts. A fifth failed attempt becomes Permanently failed.

You do not have to do anything for a transient failure to recover.

The other six need a person first.

The two buttons

They are two buttons on purpose. A single "Retry" on NOT_CONFIGURED would be worse than no button, because it implies the problem might go away on its own. It will not — the credential has to be configured. Retry now refuses those rows and tells you the actual next step instead.

Both work on one row or on a selection, capped at 200 rows per pass.

Closing a row

A reason is required for both. A queue whose rows can be cleared without saying why answers "did anyone look at this?" with silence, and that is the question an auditor asks about it.

Permanently failed is not a button. It is what the retry driver concludes after five attempts. If you want that outcome, dismiss the row and say why.

Rows also close themselves: when a later attempt assigns the record, every open row for it is closed automatically — except the notes (IMPRECISE_GEOCODE, MALFORMED_INTERSECTION), which were never what stood in the way.

Records that were deleted

The failure history outlives the record. Those rows show as <id> (record deleted) and cannot be retried — there is nothing left to assign. They stay visible rather than vanishing, which is why the queue is keyed on the source record id rather than on a lookup.

How long rows are kept

1. A closed row is deleted 90 days after it is closed — resolved, dismissed or permanently failed. The clock starts when a person finished with it, so a row resolved on its 89th day does not disappear the next morning taking its resolution note with it.
2. An open row is never deleted, at any age.
3. Deletion is permanent — the rows are purged from the recycle bin in the same pass and cannot be restored.

What a row contains: the record's id and object, the failure category, the service's error text, the record's latitude, longitude and geocode accuracy, a territory model id, and a correlation id. No name, no address, and no account field other than the coordinates already on the record.