Tailwind css migration error: "Cannot apply unknown utility class" [closed]

Question

Closed. This question needs to be more focused. It is not currently accepting answers.

Want to improve this question? Guide the asker to update the question so it focuses on a single, specific problem. Narrowing the question will help others answer the question concisely. You may edit the question if you feel you can improve it yourself. If edited, the question will be reviewed and might be reopened.

Closed 3 days ago.

Improve this question

I have a fairly large svelte kit tailwind project.

I updated all dependencies to latest, including TailwindCSS. My current dependencies are as follows:

{
    "devDependencies": {
        // ...
        "@tailwindcss/postcss": "^4.1.17",
        "autoprefixer": "^10.4.22",
        "postcss": "^8.5.6",
        "postcss-load-config": "^6.0.1",
        "vite": "^7.2.4",
        "vitest": "^4.0.13"
    },
    "dependencies": {
        // ...
        "tailwind-merge": "^3.4.0",
        "tailwind-variants": "^3.2.2",
        "tailwindcss": "^4.1.17"
    },
}

I ran pnpm update and then added ^ before all dependencies and ran pnpm i manually again.

My previous lib/css/app.postcss was:

@import 'focus.css';
@import 'fonts.css';
@import 'input.css';
@import 'pitchBlack.css';
@import 'scrollbar.css';
@import 'surface.css';
@import 'table.css';
@import 'typography.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

I have since updated it to:

@config "../../../tailwind.config.cjs";

@import './focus.css';
@import './fonts.css';
@import './input.css';
@import './pitchBlack.css';
@import './scrollbar.css';
@import './surface.css';
@import './table.css';
@import './typography.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

I also tried @import "tailwindcss"; which seems redundant of the @tailwind lines for now. I want to fix this with the minimal possible code diff.

My postcss.config.cjs was:

module.exports = {
    plugins: {
        'tailwindcss/nesting': {},
        'tailwindcss': {},
        'autoprefixer': {}
    }
}

And I changed it to:

module.exports = {
    plugins: {
        '@tailwindcss/postcss': {},
    },
}

The latest errors I am stuck on are the following:

[plugin:vite-plugin-svelte:preprocess] Error while preprocessing

/path/to/desktopclock/src/lib/components/layout/Nav.svelte - tailwindcss:

/path/to/desktopclock/src/lib/components/layout/Nav.svelte:1:1:
  Cannot apply unknown utility class `font-normal`.
  Are you using CSS modules or similar and missing `@reference`
  https://tailwindcss.com/docs/functions-and-directives#reference-directive

When I add

@reference "../../css/app.postcss";

to my Nav.svelte, then I get the following error:

[plugin:vite-plugin-svelte:preprocess] Error while preprocessing

/path/to/desktopclock/src/lib/components/layout/Nav.svelte - tailwindcss:

/path/to/desktopclock/src/lib/components/layout/Nav.svelte:1:1:
  Cannot apply unknown utility class `bg-base-300`

I have custom base and accent palettes used across my app. My tailwind config is as follows:

const plugin = require('tailwindcss/plugin');
const colors = require('tailwindcss/colors');

// https://stackoverflow.com/a/70480061/4907950
// https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo
function withOpacity(cssVariable) {
    return ({ opacityVariable, opacityValue }) => {
        if (opacityValue !== undefined) {
            return `rgba(var(${cssVariable}), ${opacityValue})`;
        }
        if (opacityVariable !== undefined) {
            return `rgba(var(${cssVariable}), var(${opacityVariable}, 1))`;
        }
        return `rgb(var(${cssVariable}))`;
    };
}

const dynamicColors = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900'].reduce(
    (obj, item) => ({
        ...obj,
        [`base-${item}`]: withOpacity(`--base-${item}`),
        [`accent-${item}`]: withOpacity(`--accent-${item}`)
    }),
    {}
);

module.exports = {
    content: ['./src/**/*.{html,js,svelte,ts}'],
    safelist: ['dark'],
    darkMode: null,
    theme: {
        borderRadius: {
            none: '0',
            DEFAULT: '0.5rem',
            full: '9999px'
        },
        boxShadow: {
            // xs: '0 1px 2px 0 rgba(0,0,0,.05)',
            // sm: '0 1px 4px 0 rgba(0,0,0,.1), 0 1px 2px rgba(0,0,0,.1)',
            md: '0 4px 6px 0 rgba(0,0,0,.1), 0 2px 4px rgba(0,0,0,.1)'
            // lg: '0 16px 24px 0 rgba(0,0,0,.1), 0 4px 6px rgba(0,0,0,.1)'
        },
        colors: {
            white: '#FFF',
            black: '#000',
            transparent: 'transparent',
            red: {
                // Used for skin tones in vector art
                200: colors.red[200]
            },
            ...dynamicColors
        },
        spacing: {
            0: '0',
            1: '0.25rem',
            2: '0.5rem',
            4: '1rem',
            6: '1.5rem',
            10: '2.5rem',
            12: '3rem', // toggles, large btn
            16: '4rem',
            24: '6rem',
            32: '8rem',
            48: '12rem',
            64: '16rem',
            80: '20rem',
            96: '24rem'
        },
        transitionDuration: {
            125: '125ms',
            250: '250ms',
            DEFAULT: '250ms'
        },
        transitionTimingFunction: {
            DEFAULT: 'linear'
        },
        extend: {
            fontSize: {
                '10xl': '10rem',
                '11xl': '12rem'
                // '12xl': '16rem',
                // '13xl': '20rem'
            },
            screens: {
                short: { raw: '(max-height: 360px)' }
            }
        }
    },
    plugins: [
        plugin(function ({ addUtilities, addVariant }) {
            addUtilities({
                '.drag-none': {
                    '-webkit-user-drag': 'none',
                    '-khtml-user-drag': 'none',
                    '-moz-user-drag': 'none',
                    '-o-user-drag': 'none',
                    'user-drag': 'none'
                }
            });
            // Ignore dark mode during print
            addVariant('dark', '@media not print { .dark & }');
        })
    ]
};

I've spent several hours on this (and I've used tailwind 3 on dozens of projects and tailwind 4 on dozens of projects with zero issues) and I cannot seem to solve it.

I do not want to move everything over, and I do not want to add an @reference line to hundreds of files. However, if that is the only option, I will be forced to do it. Based on this answer it seems like I will be forced to do both. I thought there was an easy one line command to just use the old config for now. Out of all my dependency updates, this has been by far the hardest and most painful.

What is the simplest, easiest, most minimal diff way to simply update from tailwind 3 to 4?

Related: Cannot apply unknown utility class border-border - the border-border class does not exist per TailwindCSS; even if I manually define it as a class and Tailwind 4 Utilities Failing ("Cannot apply unknown utility class") in Next.js 15 (Pages Router) Build — rozsazoltan
– rozsazoltan, Commented Nov 24 at 10:18
What is the simplest, easiest, most minimal diff way to simply update from tailwind 3 to 4? - I don't think there's a good way to do this - I would update it manually using the following references: stackoverflow.com/a/79383884/15167500 --- But there is also an upgrade tool available - make sure to run it strictly on a new Git branch to avoid any data loss: tailwindcss.com/docs/upgrade-guide (and alongside the tool, it also tries to mention the most important modifications) — rozsazoltan
– rozsazoltan, Commented Nov 24 at 10:28
It's difficult to manually migrate from TailwindCSS v3's JS-based configuration to v4, since it's not clear even from the documentation which key belongs to which namespace. I created a table for this, listing both undocumented namespaces and documented alternatives: github.com/tailwindlabs/tailwindcss/discussions/19020 — rozsazoltan
– rozsazoltan, Commented Nov 24 at 10:29

rozsazoltan · Accepted Answer · 2025-11-24 10:10:16Z

Use postcss.config.mjs instead of cjs:

https://tailwindcss.com/docs/upgrade-guide#using-postcss

You're using TailwindCSS v4, where the @tailwind directive no longer exists, so this is incorrect:

/* TailwindCSS v3 import will not working from v4 */
@tailwind base;
@tailwind components;
@tailwind utilities;

Instead, the first line of your CSS file needs to be @import "tailwindcss";:

@import "tailwindcss";

@import './focus.css';
@import './fonts.css';
@import './input.css';
@import './pitchBlack.css';
@import './scrollbar.css';
@import './surface.css';
@import './table.css';
@import './typography.css';

@config "../../../tailwind.config.cjs";

@reference is only needed in CSS modules or in <style> blocks, BUT using @apply in this manner is not recommended, for the reasons explained in the following relevant answer:

So you don't want to use @reference, and it's recommended to avoid it anyway. Instead, consistently structure the configuration of your main CSS file and ship all utilities through a single central CSS file.

Although there is backwards compatibility for using the JS configuration, it's worth studying the CSS-first configuration as well:

Collectives™ on Stack Overflow

Tailwind css migration error: "Cannot apply unknown utility class" [closed]

1 Answer 1

Comments

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Linked

Related