INVALID_KEY_OR_REF — what it means and how to fix it

When do you see INVALID_KEY_OR_REF?

• A SuiteScript or CSV import fails on record.setValue or field mapping with INVALID_KEY_OR_REF while the value looks correct in the UI.
• Setting an entity, item, account or currency that exists but is inactive, or that belongs to a subsidiary the transaction can't use.
• A workflow or integration writes an internal ID into a select field whose source list does not contain that ID.

What causes INVALID_KEY_OR_REF?

• The list value is inactive. Inactive customers, items, accounts or classifications are rejected by select fields even though the internal ID exists.
• A subsidiary restriction. In OneWorld a field only accepts records shared with the transaction's subsidiary; setting an entity or account from another subsidiary throws INVALID_KEY_OR_REF.
• A record-type mismatch. The internal ID is valid but belongs to a different record type than the field's source list expects (e.g. a vendor ID set on a customer field).
• A stale or hard-coded internal ID copied between accounts, so the ID has no matching list entry in the target account.

How do I fix INVALID_KEY_OR_REF?

Confirm the value is active, shared with the right subsidiary, and of the type the field expects - then set it by a stable lookup rather than a hard-coded ID.

1. Open the referenced record and check it is active. If it is inactive, either reactivate it or pick a valid alternative; an inactive value will never pass a select field.
2. In OneWorld, confirm the value is shared with the transaction's subsidiary. Check the record's Subsidiary field (or the shared-with list) and use a value visible to that subsidiary.
3. Confirm the internal ID is the right record type for the field. Look the value up in its source list rather than assuming - the field's source determines which type and IDs are valid.

   // verify the id exists in the field's source before setting it
           var ok = search.lookupFields({ type: search.Type.CUSTOMER, id: entityId, columns: ['isinactive'] });

4. Re-fetch IDs in the target account instead of reusing IDs from sandbox. Resolve the value at run time by external ID, name or a saved search so it is always valid for the current account.

How do I stop it happening again?

• Resolve list values at run time by external ID, name or saved search - never hard-code internal IDs that vary by account or may be deactivated.
• In OneWorld, restrict source lists and pick values that are shared with the transaction's subsidiary.
• Validate inputs before setting them: confirm the record is active and of the expected type.
• Keep master-data deactivation in mind - retiring an item or account can break integrations that still reference it.

SuiteScript version note: INVALID_KEY_OR_REF is raised identically in SuiteScript 2.0 and 2.1 and via CSV import. SuiteScript 1.0 surfaced the same condition on nlapiSetFieldValue. The diagnosis - active, subsidiary-shared, correct type - is the same across versions.

Frequently asked questions

The value exists in NetSuite - why is it invalid?

Existing is not the same as valid here. The value may be inactive, may belong to a different subsidiary than the transaction, or may be the wrong record type for the field's source list. All three throw INVALID_KEY_OR_REF even though the record exists.

How is INVALID_KEY_OR_REF different from RCRD_DSNT_EXIST?

RCRD_DSNT_EXIST means no record matches the ID and type at all. INVALID_KEY_OR_REF means the record exists but is not an allowed value for the field you set - usually inactive, wrong subsidiary, or wrong type for that field's source.

Why does it happen only in OneWorld?

OneWorld adds subsidiary restrictions to select fields. A customer, item or account that is not shared with the transaction's subsidiary is rejected, so the same value that works in a single-subsidiary account fails in OneWorld.