Troubleshoot object type mappings in Customer Profiles
This topic covers common issues when creating mappings, ingesting objects, and generating mappings with AI.
Mapping creation and validation errors
Connect Customer Customer Profiles validates a mapping when you create or update it and rejects an invalid one before any data is ingested. The error message names the specific problem—a missing or wrongly combined identifier, an unsupported target, a name that breaks the character rules, or a quota you've reached.
For the rules a mapping has to satisfy, and for the choices that are accepted but quietly degrade matching, see Before you submit. For the syntax behind each part of a mapping, see Field definitions in Customer Profiles object type mappings, Key definitions in Customer Profiles object type mappings, Standard identifiers in Customer Profiles, and Reference for standard objects in Customer Profiles.
Object ingestion errors
| Symptom | Likely cause and fix |
|---|---|
| Object rejected as invalid | The submitted object isn't valid JSON, or it can't be parsed
against the object type's fields. Verify the request body is
well-formed JSON matching the field Source
paths. |
| Missing unique or profile key | Every field that makes up the UNIQUE key, or every
PROFILE key, resolved to empty for this object.
Ensure the source data contains the values those keys depend on.
See Field definitions in Customer Profiles object type mappings. |
| Standard object type rejected at ingestion | PutProfileObject can't be called with a standard
object type name (such as _profile,
_asset, or _order). Standard objects
aren't ingested directly—they're populated as a result of
ingesting a custom object type whose fields target them. To create
or update a profile directly, use CreateProfile or
UpdateProfile. See Reference for standard objects in Customer Profiles. |
An object wasn't associated with the expected profile
If an ingested object landed on the wrong profile or created a new one unexpectedly, check the following:
-
Ambiguous match: If a
PROFILEkey value matched more than one profile, Customer Profiles discards that key. Make sure the key you rely on for matching is unique enough to identify a single profile. See Profile matching and inferred profiles in Customer Profiles. -
Normalization mismatch: Matching uses the field's
ContentType. A phone or email that isn't tagged with the right content type might not match a value stored in another format. See Field definitions in Customer Profiles object type mappings. -
LOOKUP_ONLY / NEW_ONLY keys: A key with
LOOKUP_ONLYis never stored, andNEW_ONLYis stored only on newly created profiles. If you expected to match on such a key later, it might not have been saved. See Standard identifiers in Customer Profiles. -
Ingestion timing: Ingestion takes a short time to complete. If you searched immediately after ingesting, the association might not have finished yet. See Profile matching and inferred profiles in Customer Profiles.
-
Profile creation disabled: If
AllowProfileCreationisfalseand no profile matched, the object was sent to the domain dead-letter queue instead of creating a profile.
You can use SearchProfiles to confirm which key values are associated with which profiles.
Old field values are still on a standard object after ingestion
Standard objects (such as the standard profile, _asset, or
_order) are not replaced wholesale on ingestion—they
accumulate field values across many profile objects. Re-ingesting a profile object
with the same UNIQUE key replaces only that profile object; the
standard object keeps every field that was previously written and updates only the
fields the new ingestion targets.
If a standard field looks "stale," check:
-
Targeting: Make sure the field you want to overwrite is actually targeted in the new ingestion's mapping. A field with no
Targetdoesn't write to the standard object. -
SourcePriority: When several object types target the same standard field,
SourcePrioritydecides which value wins. A lower-priority source can't overwrite a higher-priority one. See Merging behavior and source priority. -
Manual overrides: By default, values set with UpdateProfile or in the Connect Customer agent workspace aren't overwritten by ingestion. If you need an ingested value to win, configure
SourcePriorityon the object type. See Manual updates are protected by default. -
Empty source values: A field whose
Sourceresolves to empty is treated as absent—it won't blank out an existing value on the standard object.
To explicitly clear a profile field, use UpdateProfile. For more
information, see How object type mapping works in Customer Profiles and Reference for standard objects in Customer Profiles.
Generative AI mapping errors
These errors and warnings can appear when generating a mapping with generative AI. For more information, see Generate a mapping with generative AI in Customer Profiles.
Error: Could not parse object string into JSON
The object string in the request isn't valid JSON. Review it and verify that it's valid JSON.
Error: Value at 'objects' failed to satisfy constraint: Member must have length less than or equal to 5
There are too many objects in the request. Up to five are allowed. Reduce the number of objects to five or fewer.
Error: Breached limit of 120 attributes
Up to 120 attributes are allowed in a JSON object, including nested attributes. Remove attributes that don't need to be mapped.
Warning: We couldn't find a unique key, which distinguishes your data. We couldn't find a profile key, which identifies your profiles.
The model couldn't determine a valid object type from the given object. Change the input or use the manual mapping approach. For more information, see Create an object type mapping in the Connect Customer console.
