INVALID_KEY_OR_REF — what it means and how to fix it

When you see this

• 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.

Causes

• 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.

Fix

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.

Prevent it

• 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.