Troubleshoot common issues

Before you start: this guide assumes a working Druxt site. See Getting started.

This page covers the issues that account for most of the confusion reported by real users over the life of this project. Each entry is a quick answer, with a link wherever a fuller explanation exists.

"Missing Vue template" box

You're not seeing an error, this is expected. DruxtBlock and DruxtField both show this box when nothing themes them yet (other modules don't have it), and it only appears in development mode (nuxt dev). Production builds show nothing there instead.

Expand the box: it lists every valid wrapper name for that component and has a Create button that scaffolds the file for you. See Theme Druxt components for the full explanation and how the wrapper-naming system works.

Every JSON:API request 403s, even for content that should be public

Druxt gates all of its JSON:API access behind one Drupal permission: access druxt resources. Without it, requests can fail in ways that don't obviously point at that permission. Errors instead reference whatever the underlying JSON:API resource would normally require (e.g. entity display-related admin permissions) rather than the Druxt permission itself. If JSON:API access fails site-wide right after installing the Drupal Druxt module, check Drupal → People → Permissions for Access DruxtJS JSON:API resources (machine name access druxt resources) before debugging anything else. The quickstart grants this automatically. Installing Druxt on an existing site does not. See the druxt module reference for the full installation steps.

"…has been blocked by CORS policy" in the browser console

The browser is refusing a cross-origin request to Drupal. Only requests made by the browser can fail this way, so a site that server-renders fine and breaks on navigation or live data is failing here. Two fixes, pick one: configure CORS in Drupal so the backend answers cross-origin requests, or proxy the API through the frontend so no request is cross-origin (server deployments only). druxt-menu releases before 0.22.0 sent <DruxtMenu>'s browser requests straight to Drupal even with the proxy on, so a proxied site could still fail here on its menu. Request topology explains when each applies.

Writes fail while reads work, on druxt before 1.3.0

drupal/druxt releases before 1.3.0 enabled CORS but left allowedMethods empty, which matches no method. Reads pass without a preflight. A JSON:API write, or any request with an Authorization header, is preflighted and fails. Upgrade, then rebuild the cache so Drupal rebuilds its service container:

Or configure allowedMethods yourself, as Configure CORS in Drupal recommends. A site that already did was never affected.

The build fails reaching the backend (ECONNREFUSED, timeouts, 400s)

nuxt build and nuxt generate fetch schemas and content from Drupal from the machine running the build. A baseUrl that works in your browser can still be unreachable from the build: localhost inside a container is the container itself, a Docker hostname does not resolve outside its network, and a backend behind basic auth or a VPN blocks the build the same way. Confirm with curl <baseUrl>/jsonapi from the build environment. CI setups should wait for the backend to answer before starting the build. See Request topology.

The site only shows "Welcome to Nuxt"

The Nuxt scaffolder creates a default pages/index.vue, and an explicit page always wins over Druxt's wildcard route. Delete pages/index.vue and the homepage resolves through Drupal like every other path. See Decoupled routing.

Build error: the pages directory is missing

Nuxt requires a pages/ directory even when Druxt's wildcard router provides every route. Create it with a placeholder: mkdir pages && touch pages/.gitkeep.

Routes and Views paths stop resolving after a composer update

composer update brings Decoupled Router 2.0.7, and drupal/druxt 1.2.1 and earlier fatal against it: their path translator overrides onPathTranslation() without the : void return type 2.0.7 declares.

The symptom is quiet rather than loud. The fatal happens while the container rebuilds, so Drupal keeps serving from the old container and the visible effect is routes and Views paths silently not resolving, not an error page. drush cr is usually where it first shows.

Fix by upgrading to the release that includes it:

1.2.2 has the fix and also ends Drupal 8 and 9 support, so this applies on core 10 or later. See #3618675.

Enabling the module fails with an undefined function error

Call to undefined function druxt_resources() happens on drupal/druxt 1.3.0 when the module is added to a site that already has JSON:API enabled. The Extend form and drush pm:install load druxt.install without druxt.module, where 1.3.0 keeps the resource list. Upgrade:

The status report says a Druxt resource is missing

On 1.3.0 the report lists configurable_language as missing on a site without the Language module, and jsonapi_resource_config without JSON:API Extras. Nothing is broken, since the frontend never asks for a resource the site does not have. 1.3.1 stops the warning.

Composer refuses to install drupal/druxt

A stability error (minimum-stability) means a dependency's current release is below your project's floor. Allow the pre-release for that one package with a stability flag, as in composer require drupal/jsonapi_views:^1.1@beta, rather than lowering minimum-stability project-wide. See Prepare the Drupal backend.

"require() of ES Module axios" crash on a fresh install

On druxt 0.25.0 and later this is fixed: the module pins axios 0.28.0 and transpiles it. On earlier releases, Nuxt 2's webpack 4 resolves newer axios releases through their ESM entry, which the server, built as CommonJS, cannot load. Pin axios to a 0.x release (the compatibility table lists the known pins), or transpile it in nuxt.config.js:

"error:0308010C:digital envelope routines" on Node 17 or later

Node 17 moved to OpenSSL 3, which rejects the legacy hashing algorithms Nuxt 2's webpack 4 relies on. Either build on Node 16, or enable the legacy provider in the build environment:

This also works in CI and static-host build settings by prefixing the build command; Deploy a static site covers pinning the host's Node version so this stays predictable.

Builds fail on Windows

Nuxt 2 tooling and several Druxt build steps have known problems on native Windows (path separators, OpenSSL differences). Use WSL2 and run everything inside the Linux environment. That is the setup the maintainers test.

I changed a Drupal display and nothing happened on the frontend

By default, schemas are generated once, at startup or at build. Content edits show live; a rearranged display, a changed formatter or a new view mode waits for a restart of nuxt dev or a rebuild. From druxt 0.25.0, druxt.schema.refresh makes the Nuxt server regenerate a schema after each cache clear, and on every request under nuxt dev:

A static site keeps the schemas from its build, unless its own Node server serves the route with createSchemaRefresh. The schema system explains the timing.

Edited content stays stale on a server-rendered site

From druxt 0.25.0 the Nuxt server keeps the JSON:API index and the menus between requests, and with cache.content the entities, collections, Views results and routes too, for as long as Drupal's page cache max_age allows. An edit to any of them waits for that time to pass or for a cache clear. Each Nuxt process has a cache of its own, and the cache is off under nuxt dev, so the problem does not show there. Check max_age under Drupal → Configuration → Development → Performance: at the default of 0 nothing is kept and the cause is elsewhere. Then set up the clear endpoint so Drupal empties the cache on a change, and clear each process on a site that runs several: Cache Drupal responses on the Nuxt server. In code, this.$store.dispatch('druxt/clearCache') clears everything, schemas included.