nestjs/nest · error · UnknownElementException

Nest could not find ${name} element (this provider does not

Error message

Nest could not find ${name} element (this provider does not exist in the current context)

What it means

Raised by the InstanceLinksHost that backs ModuleRef lookups: `get(token)` found no entry for the token in the map of all registered instance links, so the token is not registered anywhere in the application (or the sub-application you are querying). NestJS wraps this as UnknownElementException — 'Nest could not find X element (this provider does not exist in the current context)'. Unlike the injector error, this one happens when you explicitly request an instance.

Source

Thrown at packages/core/injector/instance-links-host.ts:36

  private readonly instanceLinks = new Map<InjectionToken, InstanceLink[]>();

  constructor(private readonly container: NestContainer) {
    this.initialize();
  }

  get<T = any>(token: InjectionToken): InstanceLink<T>;
  get<T = any>(
    token: InjectionToken,
    options?: { moduleId?: string; each?: boolean },
  ): InstanceLink<T> | Array<InstanceLink<T>>;
  get<T = any>(
    token: InjectionToken,
    options: { moduleId?: string; each?: boolean } = {},
  ): InstanceLink<T> | Array<InstanceLink<T>> {
    const instanceLinksForGivenToken = this.instanceLinks.get(token);

    if (!instanceLinksForGivenToken) {
      throw new UnknownElementException(this.getInstanceNameByToken(token));
    }

    if (options.each) {
      return instanceLinksForGivenToken;
    }

    const instanceLink = options.moduleId
      ? instanceLinksForGivenToken.find(
          item => item.moduleId === options.moduleId,
        )
      : instanceLinksForGivenToken[instanceLinksForGivenToken.length - 1];

    if (!instanceLink) {
      throw new UnknownElementException(this.getInstanceNameByToken(token));
    }
    return instanceLink;
  }

View on GitHub (pinned to dd75d7bd8c)

Solutions

1. Verify the provider is actually registered: it must appear in some module's `providers` reachable from the root module.
2. Pass `{ strict: false }` to `moduleRef.get(Token, { strict: false })` to search the whole application tree instead of the current module scope.
3. For string/symbol registrations, request with the identical token value used at registration.
4. If the lookup happens in a sub-context (`app.select(...)`), either import the needed module there or query the root context.
5. Ensure the call happens after `NestFactory.create`/`app.init()` has completed.

Example fix

// before
const svc = this.moduleRef.get('PAYMENT_GATEWAY'); // registered under class token

// after
const svc = this.moduleRef.get(PaymentGatewayService, { strict: false });

import { UnknownElementException } from '@nestjs/core';

function getOrGlobal<T>(moduleRef: ModuleRef, token: Type<T> | string): T {
  try {
    return moduleRef.get(token, { strict: true });
  } catch (e) {
    if (!(e instanceof UnknownElementException)) throw e;
  }
  return moduleRef.get(token, { strict: false }); // fall back to app-wide lookup
}

When it happens

Trigger: `moduleRef.get(Token)` / `moduleRef.resolve(Token)` where no module registers that token; the token is registered only inside a lazily created context (request-scoped) while you query the static context; querying a sub-application created via `app.select()` whose scope excludes the provider; token mismatch — requesting by class while registered under a string token or vice versa; calling get() before the app is initialized.

Common situations: Dynamic plugin systems looking up optional features by token; standalone app contexts (worker/CLI) reusing modules that reference HTTP-only providers; requesting a provider from a different DI scope; typos in string tokens; unit tests creating a testing module without the provider being fetched.

Related errors

• ModuleRef cannot instantiate class (${value} is not construc
• Nest could not select the given module ("${type.name}" does
• Nest can't resolve dependencies of the ${type.toString()}

AI-assisted analysis of nestjs/nest@dd75d7bd8c (2026-08-21). Data as JSON: /api/errors/6ff2ec5dd9fab683. Report an issue: GitHub.