denoland/deno · error · TypeError

ERR_TRACE_EVENTS_CATEGORY_REQUIRED

ERR_TRACE_EVENTS_CATEGORY_REQUIRED

Error message

At least one category is required

What it means

`trace_events.createTracing(options)` enables a tracing session for a list of category strings. `options` must be an object, `options.categories` a string array, and — after those checks — a non-empty array, because a session with zero categories could never record events; empty arrays throw ERR_TRACE_EVENTS_CATEGORY_REQUIRED. Deno's polyfill mirrors Node's validation even where tracing itself is largely stubbed.

Source

Thrown at ext/node/polyfills/trace_events.ts:184

      }
      enabledTracingObjects.delete(this);
    }
  }

  get enabled() {
    return this[kEnabled];
  }

  get categories() {
    return ArrayPrototypeJoin(this[kCategories], ",");
  }
}

function createTracing(options) {
  validateObject(options, "options");
  validateStringArray(options.categories, "options.categories");
  if (options.categories.length <= 0) {
    throw new ERR_TRACE_EVENTS_CATEGORY_REQUIRED();
  }
  return new Tracing(options.categories);
}

function getEnabledCategories() {
  const seen = new SafeSet();
  for (const tracing of new SafeSetIterator(enabledTracingObjects)) {
    for (const category of new SafeArrayIterator(tracing[kCategories])) {
      seen.add(category);
    }
  }
  if (seen.size === 0) {
    return undefined;
  }
  return ArrayPrototypeJoin(ArrayFrom(seen), ",");
}

function nowMicros() {

View on GitHub (pinned to 9ad36f7a2c)

Solutions

1. Skip createTracing entirely when the category list resolves to empty
2. Fall back to a default non-empty category list such as ['node']
3. Validate and warn on empty category config at startup

Example fix

// before
const categories = cfg.traceCategories.split(",").filter(Boolean);
const tracing = traceEvents.createTracing({ categories });

// after
const categories = cfg.traceCategories.split(",").filter(Boolean);
const tracing = categories.length > 0
  ? traceEvents.createTracing({ categories })
  : null;

const categories = raw.filter((c): c is string => typeof c === "string" && c.length > 0);
const tracing = categories.length > 0
  ? traceEvents.createTracing({ categories })
  : null;

const hasTracingCategories = (o: unknown): o is { categories: string[] } =>
  typeof o === "object" && o !== null &&
  Array.isArray((o as { categories?: unknown }).categories) &&
  (o as { categories: unknown[] }).categories.length > 0;

try {
  tracing = traceEvents.createTracing({ categories });
} catch (e: any) {
  if (e?.code === "ERR_TRACE_EVENTS_CATEGORY_REQUIRED") {
    tracing = traceEvents.createTracing({ categories: ["node"] });
  } else {
    throw e;
  }
}

When it happens

Trigger: `traceEvents.createTracing({ categories: [] })`; a list built as `'node,http'.split(',').filter(Boolean)` when the config string is empty; categories computed from flags that are all disabled in some environment.

Common situations: Diagnostics tooling ported from Node; environment-specific category config that resolves to zero entries in staging; feature-flagged tracing where every category is off.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• invalid ${name}, must not be infinity or NaN
• ERR_INVALID_HTTP_TOKEN
• ERR_INVALID_HTTP_TOKEN
• ERR_HTTP_INVALID_HEADER_VALUE
• ERR_STREAM_NULL_VALUES

AI-assisted analysis of denoland/deno@9ad36f7a2c (2026-08-20). Data as JSON: /api/errors/f62ee83eaad630f3. Report an issue: GitHub.