Fix: Module Is Not Compatible in Nuxt

What Causes This Error?

This error occurs when a Nuxt module declares version requirements that don’t match your current Nuxt installation. The module may be designed for Nuxt 2 or a different Nuxt 3 version.

The Problem

[error] Module `@nuxtjs/old-module` is not compatible with Nuxt 3.

This module requires Nuxt 2.x

The Fix

Option 1: Find Nuxt 3 Version

Many modules have Nuxt 3 versions:

# Check if there's a Nuxt 3 compatible version
npm view @nuxtjs/module-name versions

# Install specific version
npm install @nuxtjs/module-name@latest

Option 2: Use Alternative Module

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    // Instead of '@nuxtjs/axios' (Nuxt 2)
    // Use built-in $fetch or ofetch

    // Instead of '@nuxtjs/pwa' (Nuxt 2)
    '@vite-pwa/nuxt',  // Nuxt 3 alternative
  ]
})

Option 3: Update Nuxt

# Update Nuxt to latest version
npx nuxi upgrade

# Or specific version
npm install nuxt@3.10.0

Common Module Migrations

Nuxt 2 → Nuxt 3 Equivalents

Nuxt 2 Module	Nuxt 3 Alternative
@nuxtjs/axios	Built-in $fetch / useFetch
@nuxtjs/auth	@sidebase/nuxt-auth
@nuxtjs/pwa	@vite-pwa/nuxt
@nuxtjs/style-resources	Vite CSS features
@nuxtjs/dotenv	Built-in (automatic)
@nuxtjs/router	File-based routing (built-in)
@nuxt/content	@nuxt/content (v2+)
@nuxtjs/i18n	@nuxtjs/i18n (v8+)

Check Module Documentation

Most official modules have Nuxt 3 versions:

# @nuxtjs/i18n for Nuxt 3
npm install @nuxtjs/i18n

# @nuxt/image for Nuxt 3
npm install @nuxt/image

# @nuxt/content for Nuxt 3
npm install @nuxt/content

Finding Compatible Versions

Check npm

# View all versions
npm view @nuxtjs/module-name versions

# Check peer dependencies
npm view @nuxtjs/module-name peerDependencies

Check GitHub

Look for:

• Release notes mentioning Nuxt 3
• nuxt3 or v3 branches
• Updated peerDependencies

Check Nuxt Modules Directory

Visit nuxt.com/modules for verified Nuxt 3 modules.

Module Compatibility Declaration

Modules declare compatibility in their code:

// Module that requires Nuxt 3.8+
export default defineNuxtModule({
  meta: {
    name: 'my-module',
    compatibility: {
      nuxt: '^3.8.0'
    }
  }
})

Overriding Compatibility (Advanced)

If you know the module works despite warnings:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    ['@nuxtjs/module-name', { /* options */ }]
  ],

  // ⚠️ Use at your own risk
  typescript: {
    shim: false
  }
})

Building Without Module

If no compatible version exists:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    // Comment out incompatible module
    // '@nuxtjs/incompatible-module'
  ]
})

Then implement functionality manually or find alternative.

Converting Nuxt 2 Modules

For custom modules, convert to Nuxt 3 syntax:

// Nuxt 2 module
export default function() {
  this.nuxt.hook('ready', () => {
    // ...
  })
}

// Nuxt 3 module
export default defineNuxtModule({
  setup(options, nuxt) {
    nuxt.hook('ready', () => {
      // ...
    })
  }
})

Community Modules

Search for community alternatives:

# Search npm for nuxt 3 modules
npm search nuxt3 <functionality>

# Or search GitHub
# "nuxt 3" + <functionality>

Reporting Issues

If a module should support your Nuxt version:

1. Check GitHub issues
2. Open an issue if none exists
3. Consider contributing a fix

Quick Checklist

• Check if Nuxt 3 version of module exists
• Update module to latest version
• Check module documentation for compatibility
• Consider alternative modules
• Update Nuxt if module needs newer version
• Remove module if no alternative exists