agent failed to apply its own field mapping: schema changed mid-run
Handles schemas changing mid-run under an agent: re-validate the mapping before each write phase and fail fast on drift. Use when a long run's writes start failing after early success. Not for initial mapping errors.
TL;DR
A long run starts fine, then an admin changes the schema mid-run and the agent's cached mapping goes stale. Re-fetch describe before each major write phase, diff it against the cached mapping, and pause with a clear error on drift instead of writing garbage. Mappings have a TTL.
Error
[ {
"message" : "Unable to create/update fields: NewField__c.",
"errorCode" : "INVALID_FIELD_FOR_INSERT_UPDATE",
"fields" : [ "NewField__c" ]
} ]Steps
- Before each write phase, re-run describe and compare to the cached schema. Expected: drift is detected before any write.
- On drift, pause the run and log exactly what changed. Expected: a clear signal, not silent corruption.
- Update the mapping for the changed fields (new names, new types). Expected: the mapping matches the live schema.
- Resume from the checkpoint with the fresh mapping. Expected: the run completes correctly.
- For very long runs, shorten the describe refresh interval. Expected: drift windows shrink.
When to use
- A run's writes fail after early batches succeeded.
- An admin deploys changes during business hours while agents run.
- After a managed package upgrade mid-day.
When not to use
- Mapping wrong from the start (fix the initial mapping).
- Single quick runs (drift is unlikely).
Tool compatibility
- Salesforce describe API; agent schema caching.
- Checkpoint and resume logic.
Variant phrasings
writes failed after early success
Schema drift; re-describe and remap.
mapping went stale mid-run
Same fix; mappings have a TTL.
Why it happens
Agents cache describe results for performance, but schemas are mutable. A cache with no refresh policy is a time bomb on long runs.
Edge cases
- Type changes are worse than renames; validate types, not just names.
- Pausing on drift needs an alert; a silently paused agent looks like a stuck agent.
- Some drift is additive (new fields); only remap when it affects your fields.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_gzKUKu2BqRLg-HpnOOWBiw