CUSTOM_VARIABLE_NOT_FOUND means the selected destination has no custom variable whose name matches the request variable. The Data Manager API reference also notes that a variable not found for a destination can be ignored, so a superficially successful request can still lose a useful field.
Use this for WordPress forms, WooCommerce orders, CRM conversions, item-level fields, and offline uploads that map business attributes into Google Ads custom variables.
Quick answer
Export the destination's configured variable names and compare them byte for byte with the payload. Verify enablement, event or item scope, destination references, and PII policy, then upload one synthetic event and retrieve diagnostics before releasing queued production rows.
What to check first
- Capture the request ID, conversion event, destination resource, destination reference, variable name, value type, item or event scope, and returned diagnostics.
- List or verify the custom variable in the destination UI and compare case, punctuation, whitespace, naming convention, and enabled status.
- Confirm destination_references routes the variable to the account that actually defines it, especially in multi-destination requests.
- Test event-level and item-level placement separately and reject values containing email, phone, name, address, or other prohibited personal information.
- Send one synthetic event, retrieve request status, and confirm the variable appears in accepted diagnostics before replaying the production queue.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Capture the failed mapping | Capture the request ID, conversion event, destination resource, destination reference, variable name, value type, item or event scope, and returned diagnostics. | The destination contains an enabled variable with the exact payload name. |
| Match the configured name | List or verify the custom variable in the destination UI and compare case, punctuation, whitespace, naming convention, and enabled status. | The variable reaches only the intended destination and scope. |
| Verify destination scope | Confirm destination_references routes the variable to the account that actually defines it, especially in multi-destination requests. | Request status confirms acceptance without custom-variable diagnostics. |
| Screen values for PII | Test event-level and item-level placement separately and reject values containing email, phone, name, address, or other prohibited personal information. | Queue replay preserves event IDs and does not duplicate the conversion. |
Why this usually happens
- CRM labels and destination variable names drift after a rename.
- A variable can exist in one Google Ads destination but not another in the same request.
- Item-level and event-level custom variables use different payload locations.
- A mapping layer can trim, normalize, or silently drop a field before the API client serializes it.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
event:
destination_references: [ads_primary]
custom_variables:
- variable: lead_quality
value: qualified
destination_references: [ads_primary]
expected_destination_variable: lead_quality
request_id: dm-cv-20260721-018
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Capture the failed mapping
- Match the configured name
- Verify destination scope
- Screen values for PII
- Test one event and status
Decision rule
Do not replay production rows until the variable name, enablement, scope, and destination reference are proven with a synthetic event. Route permanent mapping failures to correction, not automatic retry.
What to tell the client or owner
Share the privacy-safe source field, mapping version, exact variable name and scope, destination references, enablement state, request ID, serialized synthetic payload, status diagnostics, correction, and replay plan.
Production verification checklist
- The destination contains an enabled variable with the exact payload name.
- The variable reaches only the intended destination and scope.
- Request status confirms acceptance without custom-variable diagnostics.
- Queue replay preserves event IDs and does not duplicate the conversion.
Mistakes to avoid
- Do not create a new destination variable for every misspelling.
- Do not put raw PII into a custom variable value.
- Do not assume HTTP success means every optional field was used.
- Do not retry a permanent mapping error without changing the mapping.
Questions teams ask during testing
Are custom variable names case sensitive?
Treat the configured and payload names as exact identifiers. Compare the actual serialized value, including case and hidden whitespace, rather than relying on a human-readable label.
What if the variable exists but is disabled?
That is a separate documented error state. Confirm enablement and retrieve request diagnostics instead of changing the name blindly.
When HandL WP should help
HandL WP can fix WordPress and CRM field mappings before Data Manager uploads, preserve deduplication IDs, and build a permanent-error queue that does not waste retries.
If this is active on a production site, fix Data Manager API custom variable mapping.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Custom variable enablement and privacy
If the variable exists but is disabled, use the CUSTOM_VARIABLE_NOT_ENABLED fix to verify destination scope and replay only after enablement. If Google rejects the value as personal data, use the custom-variable PII rejection audit to move approved user data into the correct fields and redact telemetry.
Helpful references