# Fix NetSuite INVALID_KEY_OR_REF Error > Source: https://netray.co/erp-help/netsuite-invalid-key-or-reference-error-fix > Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems. > Section: ERP Help ## Short answer INVALID_KEY_OR_REF fires when NetSuite cannot resolve a key used to reference another record, most commonly a parent record id on record.create's initial defaultValues, a joined internal id in a saved search filter, or a foreign key style reference in a CSV import mapping, because that id does not exist, is inactive, or is not visible in the current role or subsidiary context. Fix it by confirming the referenced internal id actually exists and is accessible before the reference is used, rather than assuming a previously valid id is still good. ## Kind error ## System netsuite ## Erp Oracle NetSuite ## Module Record References / Search Joins ## Query NetSuite INVALID_KEY_OR_REF error ## Alternate Queries - NetSuite invalid key or reference error fix - INVALID_KEY_OR_REF SuiteScript - NetSuite search filter invalid internal id reference - NetSuite parent record reference error ## Applies To NetSuite SuiteScript 1.0/2.x record.create with defaultValues, N/search filters using join or internalid criteria, CSV import field mappings, all account tiers including OneWorld ## Steps ### How to fix INVALID_KEY_OR_REF **Items:** Identify which reference the error points to: a record.create({type, defaultValues}) parent/template reference, a search filter using a join, or a CSV import column mapped to an internal id. Confirm the referenced internal id exists by opening the record directly (List > record type > internal id in the URL) rather than assuming it is still valid from a previous export or hardcoded value. Check whether the referenced record is inactive; inactive records frequently still exist but are excluded from default reference resolution depending on context. On OneWorld accounts, verify the referenced record is visible under the current subsidiary context; a valid internal id in one subsidiary can be unresolvable when referenced from a transaction in a different subsidiary. For search filters using join syntax, for example a filter on a related record through internalid, confirm the join path itself is valid for the search type; a mistyped join id fails the same way as a bad reference value. For CSV imports, re-export the current mapping's reference column from the source system immediately before import rather than reusing an older export, since ids can shift after a sandbox refresh or record deletion. For integrations, do not hardcode internal ids for records like parent items, price levels, or locations across environments; look them up by a stable external id or name at runtime instead. ## Sections ### What counts as a key or reference here **Body:** This error is broader than a single API. It covers any place NetSuite expects an id that points to another record and cannot resolve it: a parent field on record.create's defaultValues, an internalid join used inside a saved search filter, a currency or price level reference on a transaction line, or a foreign key column in a CSV import mapping. In every case, the underlying problem is the same: the id supplied does not currently resolve to an accessible, existing record. ### Stale ids from exports and environment drift **Body:** The most common real-world cause is an internal id captured once, from an export, a hardcoded constant, or a script parameter, and reused later after the underlying record was deleted, renamed, or regenerated with a new id following a sandbox refresh. Sandbox refreshes in particular reset internal ids for many records to match production, which silently breaks scripts or integrations that were tested and hardcoded against the prior sandbox state. **Code:** // Fragile: hardcoded id can drift between environments rec.setValue({ fieldId: 'parent', value: 1482 }); // Sturdier: resolve by a stable external id or name at runtime var result = search.create({ type: search.Type.ITEM, filters: [['name', 'is', 'PARENT-SKU-001']], columns: ['internalid'] }).run().getRange({ start: 0, end: 1 }); rec.setValue({ fieldId: 'parent', value: result[0].getValue('internalid') }); ### OneWorld subsidiary and context visibility **Body:** On OneWorld accounts a record can exist and even have Full role-level permission granted, but still be unresolvable as a reference if it is not shared to the subsidiary of the record doing the referencing. This is a very similar failure mode to the subsidiary restriction issue behind INSUFFICIENT_PERMISSION, but here it manifests as the reference itself failing to resolve rather than a permission denial. Check the referenced record's Subsidiaries subtab (for shared records like items, price levels, and locations) against the subsidiary of the record you are creating or editing. ### Search filters using joins **Body:** A saved search or N/search filter that joins through a related record type, for example filtering a transaction search by a customer's sales rep internal id, will throw a reference error if the join field id itself is misspelled or if the joined field does not exist on that related record type. This is a schema mismatch rather than a data mismatch, and checking the search's field list in the UI builder against your scripted filter array is the fastest way to catch it. ## Pitfalls - Hardcoding internal ids for parent items, price levels, or locations that differ between sandbox and production. - Reusing an internal id captured before a sandbox refresh reset the account's record ids. - Referencing a record that exists but is not shared to the subsidiary of the record you are creating. - Referencing an inactive record without checking its active status first. - Mistyping a join field id in a scripted search filter, which fails identically to a bad data value. - Assuming a CSV import mapping that worked once will still resolve after records were deleted or renumbered. ## Ai Angle Because ERPray is grounded on your account's actual record relationships and subsidiary structure, it can check whether a given reference id is valid, active, and visible in a specific subsidiary context directly, instead of you opening each record to verify. For integrations that hardcode ids across environments, it can also help design the lookup-by-external-id pattern that avoids INVALID_KEY_OR_REF recurring after the next sandbox refresh. ## Faq ### Why did this error start appearing after a sandbox refresh? **Answer:** Sandbox refreshes reset many internal ids to match production. Any script, CSV mapping, or integration payload with hardcoded ids from the prior sandbox state will reference records that no longer have those ids, throwing INVALID_KEY_OR_REF. ### Is this the same as INVALID_FLD_VALUE? **Answer:** They are closely related but not identical. INVALID_FLD_VALUE is a general field validation failure, while INVALID_KEY_OR_REF specifically points at a broken key or join reference to another record, such as a parent, price level, or search join target. ### Can an active, permissioned record still cause this error? **Answer:** Yes, most often on OneWorld accounts where the referenced record exists and the role has permission, but the record itself is not shared to the subsidiary context of the record making the reference. ### How do I avoid this in integrations long term? **Answer:** Avoid hardcoding internal ids across environments. Look up the target record at runtime by a stable identifier, such as an external id, item name, or customer entity id, and resolve the internal id fresh in whichever environment the integration is currently running. ## Search terms INVALID_KEY_OR_REF NetSuite, NetSuite invalid reference error, NetSuite internal id resolution error, NetSuite parent record reference error, NetSuite search join error, NetSuite sandbox refresh id drift, NetSuite CSV import foreign key error, NetSuite subsidiary reference visibility --- Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json