chatwoot/chatwoot · error · Error

Custom attribute is required

Error message

Custom attribute is required

What it means

Thrown by the Chatwoot website SDK (window.$chatwoot) when deleteCustomAttribute() is called with an empty, undefined, or whitespace-only attribute key. The SDK validates arguments client-side before forwarding a 'delete-custom-attribute' postMessage to the chat widget iframe. It exists because deleting an attribute requires knowing which attribute key to remove.

Source

Thrown at app/javascript/entrypoints/sdk.js:149

      window.$chatwoot.user = user;
      IFrameHelper.sendMessage('set-user', { identifier, user });

      setCookieWithDomain(userCookieName, hashToBeStored, {
        baseDomain,
      });
    },

    setCustomAttributes(customAttributes = {}) {
      if (!customAttributes || !Object.keys(customAttributes).length) {
        throw new Error('Custom attributes should have atleast one key');
      } else {
        IFrameHelper.sendMessage('set-custom-attributes', { customAttributes });
      }
    },

    deleteCustomAttribute(customAttribute = '') {
      if (!customAttribute) {
        throw new Error('Custom attribute is required');
      } else {
        IFrameHelper.sendMessage('delete-custom-attribute', {
          customAttribute,
        });
      }
    },

    setConversationCustomAttributes(customAttributes = {}) {
      if (!customAttributes || !Object.keys(customAttributes).length) {
        throw new Error('Custom attributes should have atleast one key');
      } else {
        IFrameHelper.sendMessage('set-conversation-custom-attributes', {
          customAttributes,
        });
      }
    },

    deleteConversationCustomAttribute(customAttribute = '') {

View on GitHub (pinned to ed230f9bc0)

Solutions

1. Pass a non-empty attribute key string that was previously set via setCustomAttributes, e.g. $chatwoot.deleteCustomAttribute('plan_id')
2. If the key comes from a variable, guard it: if (key) $chatwoot.deleteCustomAttribute(key)
3. Verify the attribute was actually set earlier with setCustomAttributes / setConversationCustomAttributes before deleting

Example fix

// before
$chatwoot.deleteCustomAttribute(user.plan); // throws if user.plan is undefined

// after
if (user.plan) {
  $chatwoot.deleteCustomAttribute(user.plan);
}

const key = 'plan_id';
if (typeof key === 'string' && key.trim().length > 0) {
  window.$chatwoot.deleteCustomAttribute(key);
}

function isNonEmptyString(v) {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  window.$chatwoot.deleteCustomAttribute(key);
} catch (e) {
  console.warn('chatwoot: skipping delete, invalid attribute key', e.message);
}

When it happens

Trigger: Calling $chatwoot.deleteCustomAttribute('') , $chatwoot.deleteCustomAttribute(), or passing a variable that is undefined/null/empty string before the widget has the attribute set. The default parameter is '' so omitting the argument always throws.

Common situations: Dynamic code that derives the attribute key from user input or a data map and passes a missing key; calling delete right after page load with a value not yet populated; typos in the method name arguments; calling before setCustomAttributes ever stored the key.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Custom attributes should have atleast one key
• Identifier should be a string or a number
• User object should have one of the keys [avatar_url, email,
• no website url

AI-assisted analysis of chatwoot/chatwoot@ed230f9bc0 (2026-08-21). Data as JSON: /api/errors/e6b8125767e53291. Report an issue: GitHub.