Troubleshooting Guide
Want to resolve an error thrown by Lightning Web Runtime (LWR) on Node.js or an LWR package? Find the error message on this page and follow the corresponding guidance.
The error messages are grouped by which LWR package they're related to. To quickly navigate to the error message you want, use the Table of Contents in the right sidebar or your brower's Find tool.
Unable to load configurable module: ${filepath}
The error message returns all the modules that don't exist or fail to transpile.
Review your app's config file (lwr.config.json
) and make sure that it sets only the following configurations as modules:
hooks
route.routeHandler
moduleProviders
viewProviders
viewTransformers
assetProviders
assetTransformers
resourceProviders
${MESSAGE_PREFIX}could not authenticate. Error body:{text}
The middleware tried to request an access token from the configured Salesforce connected app, but the OAuth endpoint returned an error.
To identify the source of the error, use the Error body
text. For example, if the error message reports OAuth not set up correctly
, you should review your OAuth settings for issues.
LwrConfigValidationError
- Configuration validation errors in ${SOURCE_BY_PHASE[phase]}
This error message returns "message"
text with specific information about where the issue is located in your code. To resolve this error, make sure your app config:
- Contains only valid JSON
- Contains only valid properties
- Matches the config interface
LwrUnresolvableError [DiagnosticsError]: 404: Could not find {item} at "{filepath}"
This package returns this error when a module, bundle, resource, asset, or view wasn't found for a given specifier.
Make sure the content you're referencing is configured properly, and ensure that the filepath printed in this error message points to the correct resource.
LwrServerError [DiagnosticsError]: An error occurred during warmup: {error text}
The server failed to load configured modules into the runtime cache during startup or warmup. Use the error text
printed in this message to identify which module or modules failed to load and why.
Warmup only occurs when the WARMUP
environment variable is set to true
.
invalidMode
- No configuration found for server mode - ${mode}
Your configured server mode has to be dev
, prod
, compat
, or prod-compat
. Check your server mode and ensure it's set to one of these values.
INVALID_MIXIN_CMP
- {0} must be an Element type
LWR throws this error when you try to add NavigationMixin to an invalid resource. To correct this, add NavigationMixin to specifically a Lightning web component.
MISSING_CONTEXT
- Could not find context to perform navigation action.
To use the navigation actions navigate()
and generateUrl()
, you have to configure the context
property. Set context
to the stringified ID of the parent router container nearest to the component that's generating a URL.
The component that performs navigation actions has to be a descendant of a router (like <lwr-router-container>
) in the DOM. LWR throws this error when you set context
to an invalid router container.
MULTIPLE_ROOTS
- Router connection failed. There can only be one root router.
Router nodes like <lwr-router-container>
can be nested, but they can't be siblings in the DOM. Check your router node hierarchy to make sure it's valid.
MULTIPLE_CHILDREN
- Could not add to the navigation hierarchy. There can only be one child per navigation node.
Router nodes can have a maximum of one child. Make sure each of your routers has one child or no children.
MISSING_ROUTE
- A route cannot be created to navigate to URL "{0}"
The page reference or URL passed to navigate()
or generateUrl()
is invalid. Use the URL from the error message to identify the resource that's triggering this error, then correct it.
MISSING_URL
- A URL cannot be created to navigate to route "{0}"
The page reference or URL passed to navigate()
or generateUrl()
is invalid. Use the URL from the error message to identify the resource that's triggering this error, then correct it.
PRENAV_FAILED
- A preNavigate hook listener blocked routing to "{0}"
The preNavigate
hook of the router blocked navigation to the given page reference or URL.
MISSING_ROUTE_TEMPLATE
- A route definition must contain a "uri" property.
To configure routing for your app, you have to set the uri
property for all of your route definitions. For more information about valid values for uri
, see RouteDefinition
or LwrConfigRouteDefinition
.
INVALID_ROUTE_QUERY
- Invalid query param in route definition.
The query in the uri
property of a route definition is invalid. Review and correct your query. For more information about valid values for uri
, see RouteDefinition
or LwrConfigRouteDefinition
.
MISSING_PAGE_BINDING
- Route definition must provide page binding.
All route definitions configured for a router must have a page
property. Review your route definitions to ensure that each one includes a page
.
INVALID_PAGE_BINDING
- Invalid page binding in route definition.
The page
property of a route definition is invalid. For more information about valid values for page
, see RouteDefinition
or LwrConfigRouteDefinition
.
INVALID_URI_SYNTAX
- Invalid URI syntax. URI cannot contain *, +, (, ).
Remove any instances of *
, +
, (
, and )
from the URI that triggered this error.
VIEW_IMPORT_FAILED
- Error importing view with name "{0}", failure was: {1}.
There was an error importing the module returned by the update()
function of the route handler for the current route. This error message should include more specific information about the cause of the error.
VIEW_MISSING
- Expected a view with name "{0}" in the viewset.
RouteHandler.update()
tried to return a requested view, but the view is missing from the ViewSet
returned by update()
.
To resolve this error, make sure your ViewSet
object for your RouteDestination
contains the desired ViewInfo
object. For more information about these objects, see RouteDestination
.
VIEW_IMPORT_FAILED_WITH_SPECIFIER
- `Error importing module "{0}" from view with name "{1}", failure was: {2}.
There was an error importing the module returned by the update()
function of the route handler for the current route. This error message should include more specific information about the cause of the error.
NO_ROUTE_MATCH
- A routing match cannot be found for {0}.
The page reference or URL passed to navigate()
or generateUrl()
is invalid. Use the details in this error message to identify the input that's causing this error, and then correct it.
INVALID_ROUTE_HANDLER
- Route definition "{0}" does not have a valid route handler module.
The route handler class for a route definition is invalid.
To resolve this issue, confirm that the route handler has a default export.
DESTINATION_NOT_FOUND
- Route handler returned 404: Not Found.
The route handler update()
function for the current route returned a 404
error.
DESTINATION_ERROR
- Route handler returned error status {0}: {1}.
The route handler update()
function for the current route returned a non-404
error status.
NO_INIT_URL
- Cannot initialize a server router without a "url".
A configuration without the required url property was passed to the createServerRouter()
function. Define a URL for the server router.
unhandledRejection - Unhandled Rejection: {}
A promise threw a error during server execution. This error ususally happens during server-side rendering.
If your component invokes an asynchronous task, make sure it doesn't attempt to execute non-portable APIs like window
or document
.
This section describes how to resolve errors caused by invalid server-side rendering (SSR) configurations. For information about setting up SSR for LWR apps, see Server-Side Rendering.
Adding links during server-side rendering failed. Could not find the </head> tag.
LWR can't add links returned by getServerData
hooks to the page because it doesn't have a <head>
tag. Add a <head>
tag to the page's layout template.
Server-side rendering for "bad/cmp" failed. Falling back to client-side rendering. Reason: SSR Error
lwr.renderComponent()
failed for the given component specifier because the component isn't portable. Review the error message for more details about the source of the issue.
Node version ${nodeVersion} is not one of LWR Lambda's supported versions
Upgrade node
to a supported version. For information about which versions of node
are valid, check out lwr/package.json
and review the node
entry in the engines
section.