tailwindcss v4.0 @tailwindcss/forms "Unknown word" error

[MattLysinger]

ISSUE
I just upgraded to v4.0 from v3. and when using the @tailwindcss/forms plugin i get a "Unknown word" error. When i remove the @tailwindcss/forms plugin i do not get this error. I am not sure how to resolve this issue - any help is appreciated. Also, is the @tailwindcss/forms plugin even needed in v4.0? (i have not been able to test since i cannot get it to work).

I HAVE TRIED

1. I have tried removing everything in the .css file except @import 'tailwindcss' and @plugin '@tailwindcss/forms' but it still did not work.
2. I have tried using a tailwind.config.js file (even though not needed in v4.0) and it still did not work.

REFERENCES
I am using node v20.18.1.

The error message is shown below:

My package.json is shown below:

My vite.config is shown below:

My .css file is shown below:

[wongjn]

Could you provide an example project that reproduces the issue please?

[MattLysinger]

I am working on reproducing the issue in a example project but when i made a duplicate project (same dependencies but all the unnecessary files removed) to share i am not getting the issue. I will try to share a example project that reproduces the issue as soon as i can reproduce it outside of my "main" project.

[muhammad-fiaz]

according to error message i think its due to postcss if the project uses vite try removing the postcss.config file in your project root if it found refer: vite-installation instruction

[MattLysinger]

I do not have the postcss.config file - when i upgraded to v4 i removed it.

[wongjn]

Could you provide an example project that reproduces the issue please? It may help in debugging the issue.

[MattLysinger]

Found the problem after debugging this for 5 hours. I had the following text as a class -> [&>span]:group-last:transition <- this is what broke the @tailwindcss/forms plugin for me. Strange it did not break it in v3. This was some placeholder class i copied from a tailwind example months ago (through the browser dev tools) and forgot about. Would of been helpful if the error message told me what 'word' was causing the issue - could have saved me 5 hours.

[solutionsinurarea]

I'm running into this exact same issue. How did you manage to debug? The stack trace has absolutely 0 debuggable context for me as it doesn't even give me a proper snapshot of the part where the parser failed.

I feel like the tailwind upgrade docs are far too simple at the moment. With v3 tailwind would never cause loud runtime errors, any failures would be silent but still build. If it's going to fail, we need a debug path.

[wongjn]

Do you have a project we can look at please? We then might be able to help debug the issue.

[solutionsinurarea]

I don't right now since I can't expose the project I'm actually working on since it's on gitlab and not public. My suspicion at the moment is that the issue may be due to svelte's class: syntax it may be generating something the parser can't deal with but I'll have to create a repo myself and see if it's the case. Since I have no debug info to work with I'm not sure if that's where I should start. But my suggestion is that tailwind needs to take the lightningcss parser and show a window with the line/tokens where the parser failed or anytime something like this happens it will be impossible to find the issue in large code bases.

[MattLysinger]

I did a manual debug, meaning i made a copy of my project and started deleting code until the error stopped happening and kept doing that until i found the issue. Maybe there is a better way but that is how i did it. Yeah i was surprised that it caused my program to crash because i thought that classes that are not valid are ignored. Honestly i do not know what other way you could debug it. Because the error stops the css from compiling so you cannot look at the css, and the error message does not give you any information on where the error is in your code or what is causing the error.

[solutionsinurarea]

Thanks, unfortunately this codebase is 10s of thousands of lines and I'm not willing to do that :)

The issue is coming from the new vite plugin for sure, but it being a vite plugin means it can stop the whole code from working. I wonder if it can issue warnings for failures and keep parsing from the next component's class string instead?

[wongjn]

You could try attaching a JavaScript debugging breakpoint at the relevant stacktrace location(s) and see if any of the scopes' variables give you any clues.

[solutionsinurarea]

Thanks I'll try that in some of the entry points and see if it helps. But of course this will only help if my suspicion is true, not if the issue is in the css somewhere.

[wongjn]

I'd put the breakpoints on or near the locations of files in the error of the stack trace. For example, if we were to debug from the OP screenshot, I'd place a breakpoint at node_modules/postcss/lib/input.js:109 and work backwards from there.

[solutionsinurarea]

Well the stacktrace is telling me where the issue is happening in the library, the parser. But I don't think putting a breakpoint in the parser will lessen my workload. I may just look and see if I can figure out a way to get lightningcss to say what tokens it failed on and potentially sumbit a PR.

[solutionsinurarea]

I've tried a few different approaches to debug this and none have worked. Since the error occurs so early in the build during pre-transform I can't get breakpoints to work or even see any output if I alter the postcss plugin file. I've never worked with vite plugins or lightningcss so I'm probably missing something but I don't have the time.

Also tried using the vite-plugin-inspector which didn't show me any output from the tailwindcss vite plugin at all once I disabled hmr to stop infinite hot reloads from failed transforms. Maybe because it exited after failing to parse.

Will have to wait for a future version of tailwind to upgrade when this problem is addressed. I think putting this validation logic as a vite plugin may be a mistake as it can break builds. Hope to be proven wrong.

[solutionsinurarea]

@wongjn I'm aware of the error, I pointed it out myself in this thread. I made the repo so your team can improve the error message. UnknownWord with no context as to where to even find the 'unknown word' is terrible dx.

[solutionsinurarea]

@wongjn also (sorry if I'm spamming you) just want to make sure you saw the other two components. Each one has a different issue, and the other two are definitely unexpected cases where the parser should not fail. If they do fail, the tailwind docs should be updated with a warning.

[wongjn]

I'm not sure what you mean with the other two components. After removing the offending code from Counter.svelte, the project seems to compile with no errors.

[solutionsinurarea]

For me, on both windows and linux the following two classes also cause the unknown word build error in v4, while in v3 it correctly rendered the styles:
[&::-webkit-inner-spin-button]:appearance-none
[&_li>*]:rounded-none

The parser throws at both of these. Maybe you could try stopping and starting the server? In my testing the vite hmr server was inconsistent in reflecting the code changes on save.

[wongjn]

I did dev and build and both went through fine.

[grizhlieCodes]

Hi all, I had the same problem. I managed to get my build to work (Svelte 5, latest tailwind install in a new build)) by removing all classes that started with [& ...

The classes that caused the error:

        [&>:is(p,a,h1,h2,h3,h4,h5,h6)]:w-full
	[&>:is(p,a,h1,h2,h3,h4,h5,h6)]:max-w-[40rem]
	[&>:is(blockquote)]:max-w-[50rem] 
	[&[data-state='open']_>_*]:bg-lime-200
         [&[data-state='open']_>_*]:text-fuchsia-600

Once I removed ALL of them (not even 1 could remain, i tested this), the build worked. I honestly don't even remember writing them at this point. This worked with Tailwind 3.4 just fine, so I guess the way Tailwind is parsing is quite different..?

[solutionsinurarea]

@wongjn Should we make this into an issue? Usually after a major release I would expect small patches to iron bugs out over the following days but I'm not seeing that here and I like tailwind and would want for progress to be made on this.

[screenfluent]

Thanks for sharing! It helped after 2 hours find the issue after losing almost all hair... find out that .html file I dropped into repo as reference has [& and started to break app.css compiling process. 🤯

[mychidarko]

I just run into the same issue but was unable to solve it by removing [&. I've tried removing all instances of [[ and every [ thing I could think about, but the "Unknown word" error still pops up without any proper info to trace the error

[intuitiveminds]

I also ran into this issue using the tailwind vite plugin (using v 4.0.4), I did not have any of the above mentioned classes (starting with brackets etc.) in my code. For now the only way to fix it was to revert back to the postcss plugin.

[intuitiveminds]

@wongjn I managed to strip down my project and created a sample repository, I sent you an invite

[wongjn]

Thank you. Seems to be the after:content-[''] class tripping up PostCSS after Tailwind has done extra processing in build environment.

[intuitiveminds]

Do you think it is specific to this class or is there a general pattern that seems to throw PostCSS off the rails (e.g. a string in brackets in general or if the brackets are applied on certain breakpoints etc.)? From the comments above it seems there are a range of potentially different scenarios where the error takes place, so it would be nice to find a common root cause. Additionally it would help if PostCSS would provide more info as to which word actually is unknown 😂

[wongjn]

I'll see if I can do some more digging and get back to you.

---

Trying to narrow down the issue. Still able to recreate the issue with:

Modified main.css to be:

@import "tailwindcss/utilities.css";

Modified index.vue to:

<script setup lang="ts">
const includedFeatures = ["Foo", "Bar", "Baz"];
</script>

<template>
  <main class="" lang="de">
    <div class="">
      <div class="">
        <div class="after:content-['']">
          <div class="">
            <img class="" src="" alt="" />
          </div>
        </div>
      </div>
    </div>
  </main>
</template>

<style scoped></style>

Removing the <script> or any element further causes the error to not occur.

The error occurs because this is in the CSS being passed to PostCSS:

.after\\:content-\\[\\&\\#39\\;\\&\\#39\\;\\] {
  &::after {
    content: var(--tw-content);
    --tw-content: '';
    content: var(--tw-content);
  }
}

Trying to understand why…

---

This module with id = /path/to/project/pages/index.vue?macro=true&vue&type=script&setup=true&lang.ts is scanned by Tailwind with the content:

import { defineComponent as _defineComponent } from 'vue'
import { createElementVNode as _createElementVNode, createStaticVNode as _createStaticVNode, openBlock as _openBlock, createElementBlock as _createElementBlock } from "vue"

const _hoisted_1 = {
  class: "",
  lang: "de"
}


export default /*@__PURE__*/_defineComponent({
  __name: 'index',
  setup(__props) {

const includedFeatures = ["Foo", "Bar", "Baz"];

return (_ctx: any,_cache: any) => {
  return (_openBlock(), _createElementBlock("main", _hoisted_1, _cache[0] || (_cache[0] = [
    _createStaticVNode("<div class=\\"\\"><div class=\\"\\"><div class=\\"after:content-[&#39;&#39;]\\"><div class=\\"\\"><img class=\\"\\" src=\\"\\" alt=\\"\\"></div></div></div></div>", 1)
  ])))
}
}

})

This has the apostrophes in the after:content-[''] class encoded as after:content-[''], thus causing Tailwind to generate the rule mentioned before. The PostCSS parser then trips up on the ampersands, causing the unknown word error.

But why is this not a problem when we remove one div somewhere?

---

Because the generated code is different, that does not have the encoded HTML entities:

import { defineComponent as _defineComponent } from 'vue'
import { createElementVNode as _createElementVNode, openBlock as _openBlock, createElementBlock as _createElementBlock } from "vue"

const _hoisted_1 = {
  class: "",
  lang: "de"
}


export default /*@__PURE__*/_defineComponent({
  __name: 'index',
  setup(__props) {

const includedFeatures = ["Foo", "Bar", "Baz"];

return (_ctx: any,_cache: any) => {
  return (_openBlock(), _createElementBlock("main", _hoisted_1, _cache[0] || (_cache[0] = [
    _createElementVNode("div", { class: "" }, [
      _createElementVNode("div", { class: "after:content-['']" }, [
        _createElementVNode("div", { class: "" }, [
          _createElementVNode("img", {
            class: "",
            src: '',
            alt: ""
          })
        ])
      ])
    ], -1)
  ])))
}
}

And this difference happens with a seemingly-arbitrary threshold of 5 elements in Vue's compiler.

[wongjn]

Opened issue #16358

[dragonofmercy]

I have to same problem using @font-face with url definition inside one of my css file, the bug is present still v.4.0.9

@font-face {
    font-family: 'Roboto';
    src: url("/vendor/dragonofmercy/gaia/src/Gui/resources/fonts/roboto-regular.woff") format('woff');
    font-weight: normal;
    font-style: normal;
}

@font-face {
    font-family: 'Roboto';
    src: url('/vendor/dragonofmercy/gaia/src/Gui/resources/fonts/roboto-bold.woff') format('woff');
    font-weight: bold;
    font-style: normal;
}

.font-roboto {
    font-family: 'Roboto', sans-serif;
}

[vite] Internal server error: [postcss] C:/Users/dragon/Tailwind/build/resources/css/app.css:2931:15: Unknown word err.plugin

The error appear only if I use npm run dev, with npm run build there is no errors

[wongjn]

Consider providing a git repo that reproduces the unexpected behavior.

[HectorMF]

I have the same error, and only running in dev mode. The following causes the error:

@font-face {
font-family: 'Geist Sans';
src: url("../fonts/Geist-1.3.0/variable-woff/GeistVF.woff2") format('woff2'), url("../fonts/Geist-1.3.0/variable-woff/GeistVF.woff") format('woff');
}

[wongjn]

Consider providing a git repo that reproduces the unexpected behavior. We can then troubleshoot the issue for you.

[dantaylor]

FWIW I tried re-installing all npm packages (deleted node_modules folder and the node-package.lock file) and that worked for me. I was having the exact same error message mentioned here. hope it helps someone.

[electrocnic]

I just want to note my wyld journey here, as I tried EVERYTHING (deleting node_modules, deleting all possible dist folders and cache folders) when I commented out a bad classname in my react ts code, and it still threw the error "unknown word".

After 1 hour it finally occurred to me, that the way how tailwind is performing its treeshaking and applying its classes to the build output, is by scanning the source code for css-looking strings.

And I verified that this also happens for commented-out strings.
Tailwind will generate something from custom classnames like bg-[var(--my-bad-custom-classname)] even when I used it like

// commented out on purpose as I wanted to try to find the error source:
// const bg = 'bg-[var(--my-bad-custom-classname)]'
return <div className=''>...</div>

When I renamed the commented-out classname, it still threw the same error.

[flihub]

found error.

disable all background-image: url("data:image/svg+xml.... properties error gone.

.form-checkbox {
    appearance: none;
    padding: 0;
    print-color-adjust: exact;
    display: inline-block;
    vertical-align: middle;
    background-origin: border-box;
    user-select: none;
    flex-shrink: 0;
    height: 1rem;
    width: 1rem;
    color: oklch(0.546 0.245 262.881);
    background-color: #fff;
    border-color: oklch(0.551 0.027 264.364);
    border-width: 1px;
    --tw-shadow: 0 0 #0000;
    border-radius: 0px;
    &:focus {
      outline: 2px solid transparent;
      outline-offset: 2px;
      --tw-ring-inset: var(--tw-empty,/*!*/ /*!*/);
      --tw-ring-offset-width: 2px;
      --tw-ring-offset-color: #fff;
      --tw-ring-color: oklch(0.546 0.245 262.881);
      --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
      --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color);
      box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
    }
    &:checked {
      border-color: transparent;
      background-color: currentColor;
      background-size: 100% 100%;
      background-position: center;
      background-repeat: no-repeat;
    }
    /* &:checked {
      background-image: url("data:image/svg+xml,%3csvg viewBox='0 0 16 16' fill='white' xmlns='http://www.w3.org/2000/svg'%3e%3cpath d='M12.207 4.793a1 1 0 010 1.414l-5 5a1 1 0 01-1.414 0l-2-2a1 1 0 011.414-1.414L6.5 9.086l4.293-4.293a1 1 0 011.414 0z'/%3e%3c/svg%3e");
    } */
    &:checked:hover {
      border-color: transparent;
      background-color: currentColor;
    }
    &:checked:focus {
      border-color: transparent;
      background-color: currentColor;
    }
    &:indeterminate {
      /* background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 16 16'%3e%3cpath stroke='white' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M4 8h8'/%3e%3c/svg%3e"); */
      border-color: transparent;
      background-color: currentColor;
      background-size: 100% 100%;
      background-position: center;
      background-repeat: no-repeat;
    }
    &:indeterminate:hover {
      border-color: transparent;
      background-color: currentColor;
    }
    &:indeterminate:focus {
      border-color: transparent;
      background-color: currentColor;
    }
  }
  .form-radio {
    appearance: none;
    padding: 0;
    print-color-adjust: exact;
    display: inline-block;
    vertical-align: middle;
    background-origin: border-box;
    user-select: none;
    flex-shrink: 0;
    height: 1rem;
    width: 1rem;
    color: oklch(0.546 0.245 262.881);
    background-color: #fff;
    border-color: oklch(0.551 0.027 264.364);
    border-width: 1px;
    --tw-shadow: 0 0 #0000;
    border-radius: 100%;
    &:focus {
      outline: 2px solid transparent;
      outline-offset: 2px;
      --tw-ring-inset: var(--tw-empty,/*!*/ /*!*/);
      --tw-ring-offset-width: 2px;
      --tw-ring-offset-color: #fff;
      --tw-ring-color: oklch(0.546 0.245 262.881);
      --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
      --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color);
      box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
    }
    &:checked {
      border-color: transparent;
      background-color: currentColor;
      background-size: 100% 100%;
      background-position: center;
      background-repeat: no-repeat;
    }
    &:checked {
      /* background-image: url("data:image/svg+xml,%3csvg viewBox='0 0 16 16' fill='white' xmlns='http://www.w3.org/2000/svg'%3e%3ccircle cx='8' cy='8' r='3'/%3e%3c/svg%3e"); */
    }
    &:checked:hover {
      border-color: transparent;
      background-color: currentColor;
    }
    &:checked:focus {
      border-color: transparent;
      background-color: currentColor;
    }
  }
  .form-input {
    appearance: none;
    background-color: #fff;
    border-color: oklch(0.551 0.027 264.364);
    border-width: 1px;
    border-radius: 0px;
    padding-top: 0.5rem;
    padding-right: 0.75rem;
    padding-bottom: 0.5rem;
    padding-left: 0.75rem;
    font-size: 1rem;
    line-height: 1.5rem;
    --tw-shadow: 0 0 #0000;
    &:focus {
      outline: 2px solid transparent;
      outline-offset: 2px;
      --tw-ring-inset: var(--tw-empty,/*!*/ /*!*/);
      --tw-ring-offset-width: 0px;
      --tw-ring-offset-color: #fff;
      --tw-ring-color: oklch(0.546 0.245 262.881);
      --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
      --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);
      box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
      border-color: oklch(0.546 0.245 262.881);
    }
    &::placeholder {
      color: oklch(0.551 0.027 264.364);
      opacity: 1;
    }
    &::-webkit-datetime-edit-fields-wrapper {
      padding: 0;
    }
    &::-webkit-date-and-time-value {
      min-height: 1.5em;
    }
    &::-webkit-date-and-time-value {
      text-align: inherit;
    }
    &::-webkit-datetime-edit {
      display: inline-flex;
    }
    &::-webkit-datetime-edit {
      padding-top: 0;
      padding-bottom: 0;
    }
    &::-webkit-datetime-edit-year-field {
      padding-top: 0;
      padding-bottom: 0;
    }
    &::-webkit-datetime-edit-month-field {
      padding-top: 0;
      padding-bottom: 0;
    }
    &::-webkit-datetime-edit-day-field {
      padding-top: 0;
      padding-bottom: 0;
    }
    &::-webkit-datetime-edit-hour-field {
      padding-top: 0;
      padding-bottom: 0;
    }
    &::-webkit-datetime-edit-minute-field {
      padding-top: 0;
      padding-bottom: 0;
    }
    &::-webkit-datetime-edit-second-field {
      padding-top: 0;
      padding-bottom: 0;
    }
    &::-webkit-datetime-edit-millisecond-field {
      padding-top: 0;
      padding-bottom: 0;
    }
    &::-webkit-datetime-edit-meridiem-field {
      padding-top: 0;
      padding-bottom: 0;
    }
  }
  .form-select {
    appearance: none;
    background-color: #fff;
    border-color: oklch(0.551 0.027 264.364);
    border-width: 1px;
    border-radius: 0px;
    padding-top: 0.5rem;
    padding-right: 0.75rem;
    padding-bottom: 0.5rem;
    padding-left: 0.75rem;
    font-size: 1rem;
    line-height: 1.5rem;
    --tw-shadow: 0 0 #0000;
    &:focus {
      outline: 2px solid transparent;
      outline-offset: 2px;
      --tw-ring-inset: var(--tw-empty,/*!*/ /*!*/);
      --tw-ring-offset-width: 0px;
      --tw-ring-offset-color: #fff;
      --tw-ring-color: oklch(0.546 0.245 262.881);
      --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
      --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);
      box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
      border-color: oklch(0.546 0.245 262.881);
    }
    /* background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 20 20'%3e%3cpath stroke='oklch(0.551 0.027 264.364)' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.5' d='M6 8l4 4 4-4'/%3e%3c/svg%3e"); */
    background-position: right 0.5rem center;
    background-repeat: no-repeat;
    background-size: 1.5em 1.5em;
    padding-right: 2.5rem;
    print-color-adjust: exact;
    &:where([size]:not([size="1"])) {
      background-image: initial;
      background-position: initial;
      background-repeat: unset;
      background-size: initial;
      padding-right: 0.75rem;
      print-color-adjust: unset;
    }
  }
  .form-textarea {
    appearance: none;
    background-color: #fff;
    border-color: oklch(0.551 0.027 264.364);
    border-width: 1px;
    border-radius: 0px;
    padding-top: 0.5rem;
    padding-right: 0.75rem;
    padding-bottom: 0.5rem;
    padding-left: 0.75rem;
    font-size: 1rem;
    line-height: 1.5rem;
    --tw-shadow: 0 0 #0000;
    &:focus {
      outline: 2px solid transparent;
      outline-offset: 2px;
      --tw-ring-inset: var(--tw-empty,/*!*/ /*!*/);
      --tw-ring-offset-width: 0px;
      --tw-ring-offset-color: #fff;
      --tw-ring-color: oklch(0.546 0.245 262.881);
      --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
      --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);
      box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
      border-color: oklch(0.546 0.245 262.881);
    }
    &::placeholder {
      color: oklch(0.551 0.027 264.364);
      opacity: 1;
    }
  }