What causes "Starfield: No container element found." in krahets/hello-algo?

Ensure an element with class `starfield` exists in the DOM before calling setup, or pass `{ container: myEl }` explicitly.

krahets/hello-algo · error · Error

Starfield: No container element found.

Error message

Starfield: No container element found.

What it means

Thrown by setup() in the starfield animation module when no container element can be resolved. The container is taken from `config.container` if provided, otherwise from `document.querySelector('.starfield')`. If neither yields an element, setup aborts with this Error before any canvas is created.

Source

Thrown at overrides/javascripts/starfield.js:90

    return originRect.top - containerRect.top + originRect.height / 2;
  }

  function getOriginX(origin, container) {
    const originRect = origin.getBoundingClientRect();
    const containerRect = container.getBoundingClientRect();
    return originRect.left - containerRect.left + originRect.width / 2;
  }

  /**
   * Set up and start the starfield animation.
   * @param {Object} userConfig Configuration options.
   */
  function setup(userConfig = {}) {
    Object.assign(config, userConfig);

    container = config.container || document.querySelector(".starfield");
    if (!container) {
      throw new Error("Starfield: No container element found.");
    }
    // container.style.position = "relative";

    width = container.clientWidth;
    height = container.clientHeight;

    canvas = document.createElement("canvas");
    canvas.width = width;
    canvas.height = height;

    canvas.style.position = "absolute";
    canvas.style.top = "0";
    canvas.style.left = "0";
    canvas.style.width = "100%";
    canvas.style.height = "100%";
    canvas.style.zIndex = "-1";
    canvasRGB = parseRGBA(config.canvasColor);

View on GitHub (pinned to 69932aed18)

Solutions

Ensure an element with class `starfield` exists in the DOM before calling setup, or pass `{ container: myEl }` explicitly.
Defer setup until after DOMContentLoaded (or place the script at end of body / use `defer`).
In SPAs, re-query the container on each route change and pass it explicitly.
Verify the override/template actually renders the `.starfield` element (check MkDocs `theme.custom_dir` / overrides path).

Example fix

// before
starfield.setup({ auto: true });

// after
const el = document.querySelector('.starfield');
if (el) starfield.setup({ container: el, auto: true });

Defensive patterns

Strategy: validation

Validate before calling

// Resolve (or pass) the container before setup.
const container = document.querySelector('.starfield');
if (container) {
  starfield.setup({ container, auto: false });
}

Type guard

function starfieldContainerReady(config) {
  const el = (config && config.container) || document.querySelector('.starfield');
  return el instanceof HTMLElement;
}

Try / catch

try {
  starfield.setup(userConfig);
} catch (e) {
  if (e instanceof Error && /No container element found/.test(e.message)) {
    // render a placeholder or skip the effect
  } else throw e;
}

Prevention

Run setup after DOMContentLoaded or with a deferred script.
Pass `{ container: el }` explicitly in SPAs after each route render.
Confirm the theme override actually emits the `.starfield` element.
Re-query the container on every init; do not cache across navigation.

When it happens

Trigger: Calling starfield.setup() on a page that has no element with class `starfield` and no `container` in the config; calling setup before the DOM is ready (script ran in <head> without defer); CSS class typo so the selector misses; the container was removed/replaced after a SPA route change.

Common situations: MkDocs/Material theme where the starfield is an override: the `.starfield` block is conditional on a config flag and is absent; bundler or build strips the element; SPA navigation tears down the node before setup runs; running setup twice after the first instance consumed the node.

Related errors

AI-assisted analysis of krahets/hello-algo@69932aed18 (2026-08-13). Data as JSON: /api/errors/873dae295bd608f5. Report an issue: GitHub.