Framework diagnostics reference

Map every stable framework diagnostic code to its boundary, structured error contract, and first remediation step.

Preserve the structured TavoError

TavoError carries a stable code, message, optional structured details, remediation hint, and cause. Check isTavoError before reading those fields. formatTavoError preserves the code and appends the hint for human output.

Branch on code, not on message text.
Treat details and cause as potentially sensitive before logging them.
Do not convert an error code into a successful process exit in build or verification tooling.

tsimport {
  formatTavoError,
  isTavoError
} from "@tavojs/core";

export async function startApplication(): Promise<void> {
  try {
    await initializeApplication();
  } catch (error) {
    if (isTavoError(error)) {
      logger.error({
        code: error.code,
        details: error.details,
        message: formatTavoError(error)
      });
      return;
    }

    throw error;
  }
}

Pages, SSR, and configuration codes

API / contract	Type / boundary	Default / result	Behavior
`TAVO_PAGES_001`	`runtime configuration`	error	The resolved-page cache limit is invalid. Supply a finite non-negative `maxResolvedCacheEntries` value.
`TAVO_PAGES_002`	`browser boot`	error	The client root element is missing. Align `bootTavo` `rootId` with the HTML shell.
`TAVO_PAGES_003`	`page discovery`	error	A dynamic discovery pattern is unsupported. Use the standard literal glob or explicit modules.
`TAVO_PAGES_004`	`page discovery`	error	The bundler page-discovery API is unavailable. Use `Tavo.js`'s Vite wrapper or explicit modules.
`TAVO_PAGES_005`	`server bootstrap`	error	The server bootstrap is missing page modules. Pass the discovered modules map.
`TAVO_PAGES_006`	`route manifest`	error	A page declares conflicting static generation options. Choose named prerender or helper static, not both.
`TAVO_SSR_001`	`Node handler`	error	`canonicalOrigin` is not a credential-free HTTP(S) origin without a path, query, or hash.
`TAVO_CONFIG_001`	`client build`	error	A server-only module reached the browser graph. Move the import behind a server loader, action, middleware, or server plugin phase.
`TAVO_CONFIG_002`	`client build`	error	A likely secret environment value is referenced from browser code. Keep it server-only and expose only deliberate VITE_ values.
`TAVO_HYDRATION_001`	`strict hydration`	error	Strict hydration found a server/client mismatch. Fix the first reported DOM path and phase.

Plugin API v1 codes

API / contract	Type / boundary	Default / result	Behavior
`TAVO_PLUGIN_001`	`compatibility`	error	The descriptor is missing Plugin API version 1 or targets an unsupported version.
`TAVO_PLUGIN_002`	`identity / manifest`	error	Plugin identity, configuration input, manifest authority, or a hydrated store declaration is invalid.
`TAVO_PLUGIN_003`	`ownership`	error	An installation or contribution duplicates ownership without an exact valid override.
`TAVO_PLUGIN_004`	`dependency / capability`	error	A required plugin, version, capability, request resource, or declared owner is unavailable.
`TAVO_PLUGIN_005`	`dependency / ordering`	error	A plugin dependency, middleware order, or capability resolution graph contains a cycle.
`TAVO_PLUGIN_006`	`authority / permission`	error	A plugin requested a reserved resource, undeclared exposure, invalid override, or missing permission.
`TAVO_PLUGIN_007`	`phase implementation`	error	A loaded phase does not implement exactly the contributions declared by its manifest.
`TAVO_PLUGIN_008`	`initialize / build`	error	A phase loader, setup hook, capability/store factory, or build contribution failed.
`TAVO_PLUGIN_009`	`request / dispose`	error	Plugin middleware, an endpoint, a request capability, or request/runtime disposal failed.

Plugin graph diagnostics include severity, phase, message, and optional resource, owners, and hint.
Use tavo inspect plugins or tavo inspect plugins --json for the supported project workflow.
Experimental tooling can import inspectPluginGraph from @tavojs/core/dev; compilation, request dispatch, and runtime disposal remain framework host responsibilities.

Capture browser runtime context

tsimport {
  configureDevDiagnostics
} from "@tavojs/core/dev";

export function enableStrictDiagnostics(): () => void {
  configureDevDiagnostics({
    enabled: true,
    devMode: true,
    strictHydration: true,
    onTrace(event) {
      console.debug(event.phase, event.path);
    },
    onHydrationMismatch(event) {
      console.error(event.path, event.kind, event.recovery);
    },
    onError(error) {
      console.error(error);
    }
  });

  return function disableStrictDiagnostics() {
    configureDevDiagnostics({
      enabled: false,
      devMode: false,
      strictHydration: false,
      onTrace: null,
      onHydrationMismatch: null,
      onError: null
    });
  };
}

Choose the matching verifier

doctor reports project-shape issues without performing a production build.
check adds the project's typecheck script when available.
inspect plugins validates ownership and authority before phases are executed.
verify --smoke adds lightweight route checks; build remains the production compiler and prerender authority.
A parseable JSON envelope can still represent failure. Check both ok and the process exit status.

BASH

bashnpx tavo doctor --json
npx tavo check --json
npx tavo inspect plugins --json
npx tavo verify --smoke --json
npx tavo build

Look up exact public types

Follow linked API names to their canonical TypeScript declarations and package boundaries.