Skip to Content
ErrorsNEXUS_PROVIDER_FAILED

This page documents the 0.4 release candidates of @nexusdi/core. The newest on npm is 0.4.0-rc.1. The documentation for 0.3.2, the current release, is at nexus.js.org. Try the release candidate.

NEXUS_PROVIDER_FAILED

NEXUS_PROVIDER_FAILED means a constructor, a factory, an onInit or an options validation threw while the container built a provider. Nexus.create and load() reject with it after disposing what they had built, and createScope does the same. scope.extend() rejects with it too, after rolling back what it built. The first get() of an eager: false provider throws it. The original error is its cause.

Reproduce NEXUS_PROVIDER_FAILED

The region binds NavCharts to an async factory that throws. Without a plugin, core prints a one-line message that starts with the code and ends with the address of this page. With errors() from @nexusdi/errors registered (npm install @nexusdi/errors@next), the same error carries the full text and its fix.

import { Nexus, Token, defineModule, isNexusError } from '@nexusdi/core';
import { provide } from '@nexusdi/core';
import { errors } from '@nexusdi/errors';
 
interface INavCharts {
  plot(to: string): string;
}
const NAV_CHARTS = new Token<INavCharts>('NavCharts');
 
async function downloadCharts(): Promise<INavCharts> {
  throw new Error('subspace link down');
}
 
const Tactical = defineModule({
  name: 'Tactical',
  providers: [provide(NAV_CHARTS, { useFactory: downloadCharts })],
});
 
const thin = await Nexus.create(Tactical).catch((error: unknown) => error);
if (!isNexusError(thin, 'NEXUS_PROVIDER_FAILED')) throw thin;
const line = thin.message; // -> '[NEXUS_PROVIDER_FAILED] token=NavCharts module=Tactical path=NavCharts. https://nexus.js.org/errors/NEXUS_PROVIDER_FAILED'
console.log(line);
const cause = String(thin.cause); // -> 'Error: subspace link down'
console.log(cause);
 
const full = await Nexus.create(Tactical, { plugins: [errors()] }).catch(
  (error: unknown) => error,
);
const text = isNexusError(full) ? full.message.split('\n') : null; // -> ['[NEXUS_PROVIDER_FAILED] NavCharts (module Tactical) failed: Error: subspace link down']
console.log(text);

Try it: save the region as error.ts and run npx tsx error.ts. thin.cause holds the error the factory threw. It prints the one-line message, the cause and the full text. Then save the fix region below as fixed.ts and run npx tsx fixed.ts. It prints cached course to Kepler-442b.

Fix NEXUS_PROVIDER_FAILED

NEXUS_PROVIDER_FAILED is fixed by correcting what cause reports. When the failure is expected, such as a network call at startup, handle it inside the factory. Here the factory falls back to cached charts.

import { Nexus, Token, defineModule, provide } from '@nexusdi/core';
 
interface INavCharts {
  plot(to: string): string;
}
const NAV_CHARTS = new Token<INavCharts>('NavCharts');
 
const cachedCharts: INavCharts = { plot: (to) => `cached course to ${to}` };
 
async function downloadCharts(): Promise<INavCharts> {
  throw new Error('subspace link down');
}
 
const Tactical = defineModule({
  name: 'Tactical',
  providers: [
    provide(NAV_CHARTS, {
      useFactory: () => downloadCharts().catch(() => cachedCharts),
    }),
  ],
  exports: [NAV_CHARTS],
});
 
await using ship = await Nexus.create(Tactical);
const course = ship.get(NAV_CHARTS).plot('Kepler-442b'); // -> 'cached course to Kepler-442b'
console.log(course);

Try it: in fixed.ts, replace downloadCharts().catch(() => cachedCharts) with downloadCharts() and run it again. Nexus.create rejects with a ProviderError for NavCharts in Tactical, and its cause is Error: subspace link down. Put the .catch back and the program prints cached course to Kepler-442b again.

Fields of ProviderError

ProviderError carries these fields, and the standard cause:

  • token: the display name of the provider that failed.
  • module: its module.
  • path: the providers being built when it failed. At create, load() and createScope it lists only the failing provider, unless the failure happened while building a transient or eager: false dependency, which the path then includes: a singleton S over a throwing transient factory T gives ['S', 'T']. A get() of an eager: false chain lists the whole chain, from the first requested provider to the failing one.
  • alsoFailed: other providers of the same startup level that failed too. Each entry names the provider by token and module and holds its cause.
  • disposalErrors: errors thrown while disposing what the operation had built.
ErrorsRegister a plugin