solidjs/solid · error · Error

getNextContextId cannot be used under non-hydrating context

Error message

getNextContextId cannot be used under non-hydrating context

What it means

sharedConfig.getNextContextId() increments and returns the hydration context counter, which only exists during server rendering/hydration. Calling it with no sharedConfig.context (outside a render pass) throws. createUniqueId and hydration-aware code paths call this internally, so the error frequently surfaces indirectly.

Source

Thrown at packages/solid/src/server/rendering.ts:119

  if (t === "object") return node.t;
  if (t === "function") return resolveSSRNode(node());
  return String(node);
}

type SharedConfig = {
  context?: HydrationContext;
  getContextId(): string;
  getNextContextId(): string;
};
export const sharedConfig: SharedConfig = {
  context: undefined,
  getContextId() {
    if (!this.context) throw new Error(`getContextId cannot be used under non-hydrating context`);
    return getContextId(this.context.count);
  },
  getNextContextId() {
    if (!this.context)
      throw new Error(`getNextContextId cannot be used under non-hydrating context`);
    return getContextId(this.context.count++);
  }
};

function getContextId(count: number) {
  const num = String(count),
    len = num.length - 1;
  return sharedConfig.context!.id + (len ? String.fromCharCode(96 + len) : "") + num;
}

function setHydrateContext(context?: HydrationContext): void {
  sharedConfig.context = context;
}

function nextHydrateContext(): HydrationContext | undefined {
  return sharedConfig.context
    ? {
        ...sharedConfig.context,

View on GitHub (pinned to f47845f9cc)

Solutions

1. Move createUniqueId()/getNextContextId() calls inside component bodies so they run during render
2. Guard with sharedConfig.context before calling the API directly
3. Use your own id source for values needed before rendering begins

Example fix

// before (module scope, SSR)
const uid = createUniqueId(); // getNextContextId throws: no context

// after
let uid: string;
const MyComponent = () => {
  uid = createUniqueId(); // runs inside render
  return <div id={uid} />;
};

import { sharedConfig } from 'solid-js/web';
let uid: string;
if (sharedConfig.context) uid = createUniqueId();
else uid = crypto.randomUUID();

const hasHydrationContext = (sc: typeof sharedConfig): boolean => !!sc.context;

try { return sharedConfig.getNextContextId(); } catch (e) { if (/non-hydrating context/.test(String(e))) return fallbackId(); throw e; }

When it happens

Trigger: Calling createUniqueId() or sharedConfig.getNextContextId() on the server outside the render tree; module-level initialization code that creates components/ids before render starts; utilities extracted out of the render lifecycle.

Common situations: Top-level const id = createUniqueId() in a server-rendered module; refactoring component code into module scope; library initialization running before renderToString/renderToStream establishes a context.

Related errors

• getContextId cannot be used under non-hydrating context
• Expected the observer to be an object.
• Attempting to use server context in non-server build
• Expected the observer to be an object.
• Dispose method must be an explicit argument to createRoot fu

AI-assisted analysis of solidjs/solid@f47845f9cc (2026-08-27). Data as JSON: /api/errors/f88428368614250a. Report an issue: GitHub.