Why Tailwindcss throws "unknown utility class"

daily email Kamal

Over the weekend, I ran into a deployment issue using Kamal and TailwindCSS. Everything had been working fine until I suddenly started seeing this error during asset precompilation:

#16 [build 6/6] RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile
#16 2.683 Error: Cannot apply unknown utility class: py-2
#16 2.694 bin/rails aborted!

There were no recent changes to the codebase that would explain it.

What Happened?

After digging into the issue and checking GitHub discussions, I found that the root cause was a platform mismatch during Docker image builds. This may have been triggered by a recent macOS update, which seems to have affected how native binaries behave when building images for a different architecture. Specifically:

TailwindCSS v4 uses native binaries
I was building the Docker image on an Apple Silicon (arm64) Mac
The production server is AMD64 (x86_64)

Because the binaries are architecture-specific, the image built on my local machine didn’t work correctly when deployed. This led to Tailwind silently failing during asset precompilation.

The Fix: Use a Remote Builder

Kamal provides an option to build images on a remote server, which solves the architecture mismatch. Here’s how I updated my configuration to build the image on one of the app’s AMD64 worker servers:

# config/kamal.yml
builder:
  arch: amd64
  # Add this line with your remote IP address
  # I used one of the existing worker servers
  remote: ssh://root@1.2.3.4

This ensures that the Docker image is built on the correct architecture for production, which resolved the issue immediately.

Pros

Uses existing infrastructure (no extra cost)
Avoids cross-compilation setup

Cons

Slightly slower builds on remote hosts
Temporary CPU load on the worker server during build

If needed, you can add a dedicated build server later for more stability or performance.

If you’re using Kamal to deploy from an M1 or M2 Mac to an AMD64 server and run into errors during TailwindCSS asset compilation, the issue may be due to an architecture mismatch. Using Kamal’s remote builder option is a straightforward way to fix the problem.