dianping/cat · error · Error

Invalid `{name}` option provided. Please provide a CSS selec

Error message

Invalid `{name}` option provided. Please provide a CSS selector or a plain HTML element.

What it means

Dropzone.getElement(el, name) resolves option values that should point at DOM nodes (previewsContainer, clickable). A string is passed to document.querySelector; an object is accepted only if it has nodeType. If the result is null — selector matched nothing, or the value was neither string nor node — it throws, naming the offending option.

Source

Thrown at cat-home/src/main/webapp/assets/js/uncompressed/dropzone.js:1652

      return true;
    }
    while (element = element.parentNode) {
      if (element === container) {
        return true;
      }
    }
    return false;
  };

  Dropzone.getElement = function(el, name) {
    var element;
    if (typeof el === "string") {
      element = document.querySelector(el);
    } else if (el.nodeType != null) {
      element = el;
    }
    if (element == null) {
      throw new Error("Invalid `" + name + "` option provided. Please provide a CSS selector or a plain HTML element.");
    }
    return element;
  };

  Dropzone.getElements = function(els, name) {
    var e, el, elements, _i, _j, _len, _len1, _ref;
    if (els instanceof Array) {
      elements = [];
      try {
        for (_i = 0, _len = els.length; _i < _len; _i++) {
          el = els[_i];
          elements.push(this.getElement(el, name));
        }
      } catch (_error) {
        e = _error;
        elements = null;
      }
    } else if (typeof els === "string") {

View on GitHub (pinned to e815e74d4c)

Solutions

1. Verify the selector matches an existing element before constructing the Dropzone.
2. Pass a raw DOM node (document.querySelector(...) result), not a jQuery object, when not using a selector string.
3. Ensure the container element is rendered before Dropzone initialization.

Example fix

// before
new Dropzone('#up', { url: '/upload', previewsContainer: '#previews' }); // #previews missing

// after
var prev = document.querySelector('#previews');
new Dropzone('#up', {
  url: '/upload',
  previewsContainer: prev || undefined // or ensure the element exists in markup
});

function resolveDropzoneElement(v) {
  if (typeof v === 'string') return document.querySelector(v);
  if (v && v.nodeType === 1) return v;
  return null;
}
var previews = resolveDropzoneElement(opts.previewsContainer);
if (previews) opts.previewsContainer = previews; else delete opts.previewsContainer;

function isPlainElement(v) {
  return !!v && (typeof v === 'string' || (typeof v === 'object' && v.nodeType === 1));
}

When it happens

Trigger: new Dropzone(el, { previewsContainer: '#previews' }) when #previews does not exist; clickable: '.dz-click-trigger' with a typo; previewsContainer pointing at an element inside the dropzone template that is created later; passing a jQuery object ($( ... )) instead of a raw node — jQuery objects have no nodeType.

Common situations: Preview containers living in a different AJAX-loaded partial; passing jQuery collections where the API expects DOM elements; selectors valid on the demo page but not in the app's markup.

Related errors

• Invalid dropzone element.
• Invalid `{name}` option provided. Please provide a CSS selec
• Must choose at least one picker
• failed to require "{name}"
• Dropzone already attached.

AI-assisted analysis of dianping/cat@e815e74d4c (2026-08-14). Data as JSON: /api/errors/1ea28a27528cb736. Report an issue: GitHub.