Quilt Mods Not Working? Here's How to Fix It (2026)

Are your Quilt mods not working? You installed the Quilt Loader, dropped some mods into the mods folder, launched Minecraft — and something is wrong. Maybe the mods do not appear, the game crashes on startup, or it loads as if no mods are installed at all. This guide covers the most common causes and fixes, starting with the issue that accounts for the vast majority of Quilt mod problems.

If you have not set up Quilt yet or suspect your installation may be incomplete, start with our How to Install Quilt Mods guide for a clean setup walkthrough.

Quick Checklist

Before diving into detailed troubleshooting, run through this list. Most Quilt mod issues come down to one of these:

• Is Quilted Fabric API (QFAPI) installed? — This is the #1 cause. See below.
• Do all mods target the same Minecraft version? — A mod for 1.20.4 may not work on 1.21.4.
• Are you launching the Quilt profile? — Not the vanilla or Fabric profile.
• Are the mods in the correct folder? — .minecraft/mods/
• Are any mods Forge-only? — Forge mods do not work on Quilt.
• Did you install both QFAPI and Fabric API? — You only need QFAPI. Having both can cause conflicts.
• Is Java up to date? — Minecraft 1.20.5+ requires Java 21.

Missing QFAPI — The #1 Issue

This is by far the most common reason mods fail to work on Quilt. If you are trying to use Fabric mods on Quilt (which is what most Quilt users do, since the Quilt-native mod selection is small), you need Quilted Fabric API (QFAPI) installed. Without it, Fabric mods have no API to hook into and will either silently fail to load or crash the game.

Symptoms

• Mods do not appear in the game at all
• Minecraft crashes with errors mentioning "fabric-api", missing dependencies, or unresolved modules
• The game loads but behaves like vanilla Minecraft despite having mods in the folder

The Fix

1. Download QFAPI (bundled with Quilt Standard Libraries) from Modrinth
2. Make sure you download the version that matches your Minecraft version
3. Place the QFAPI .jar in your .minecraft/mods/ folder alongside your other mods
4. If you have a standalone Fabric API jar in the same folder, remove it — QFAPI already includes Fabric API compatibility, and having both can cause conflicts
5. Relaunch the game

Why does Quilt need this? Quilt does not bundle Fabric API out of the box. QFAPI is a separate download that provides the compatibility bridge between Fabric mods and the Quilt loader. For the full explanation of how this works, see our What Is Quilt? guide.

Version Mismatch

After QFAPI issues, version mismatch is the second most common cause of mods not working. Minecraft mods are generally built for specific game versions, and mixing versions can cause crashes or mods silently failing to load.

What to Check

1. Mod version vs Minecraft version — a mod built for Minecraft 1.20.x will generally not work on 1.21.x. Check the mod's download page for supported versions.
2. QFAPI version vs Minecraft version — QFAPI also targets specific Minecraft versions. Make sure your QFAPI matches your game version.
3. Quilt Loader version — while the loader is usually more flexible, running a very outdated loader version with newer mods may cause issues. Update the loader through the Quilt Installer if needed.

The Fix

1. Pick one target Minecraft version (for example, 1.21.4)
2. Download QFAPI for that exact version
3. Download each mod for that exact version
4. If a mod does not have a release for your version, you may need to choose a different Minecraft version or find an alternative mod

Mods in the Wrong Folder

Mods must be placed directly in the .minecraft/mods/ folder as .jar files. Common mistakes include:

• Placing mods in a subfolder inside mods/ (for example, mods/quilt/) — mods should be at the top level
• Leaving mods as .zip files — they need to be .jar files
• Using the wrong Minecraft directory — if you have multiple installations or launcher instances, each has its own mods folder

The correct paths by operating system:

• Windows: %appdata%\.minecraft\mods\
• macOS: ~/Library/Application Support/minecraft/mods/
• Linux: ~/.minecraft/mods/

Missing Dependencies

Some mods require other mods to function. For example, Iris Shaders requires Sodium. If a dependency is missing, the game may crash or the mod may not load.

1. Check the mod's page on Modrinth or CurseForge — dependencies are listed under "Requirements" or "Dependencies"
2. Download any required dependencies for the same Minecraft version
3. Place them in the mods/ folder alongside the main mod

QFAPI covers the Fabric API dependency that most Fabric mods require, but some mods have additional dependencies beyond Fabric API. If the crash log mentions a specific missing mod, that is usually the dependency you need to install.

Mod Conflicts on Quilt

When two mods modify the same part of the game, they can conflict. This is not unique to Quilt — it happens on every mod loader. Symptoms include crashes with "mixin conflict" errors, visual glitches, or unexpected behavior.

How to Isolate a Conflict

1. Remove all mods except QFAPI from the mods/ folder
2. Add mods back one at a time, launching the game after each addition
3. When the game crashes or the problem reappears, the last mod you added is likely involved in the conflict
4. Try removing just that mod and see if the issue resolves

This process can be tedious with a large mod list, but it is the most reliable way to identify which mod is causing the problem.

Quilt-Specific Crash Causes

Some issues are more specific to Quilt than to mod loaders in general:

• QFAPI and Fabric API both installed — if you have both Quilted Fabric API and a standalone Fabric API jar in your mods folder, they can conflict. Remove the standalone Fabric API and keep only QFAPI.
• Mods that check for Fabric Loader specifically — a small number of mods include code that checks whether Fabric Loader (not just Fabric API) is present. These mods may not recognize Quilt Loader and refuse to start. This is uncommon but does happen.
• Outdated QFAPI — if your QFAPI version is significantly behind the Fabric API version that newer mods expect, compatibility may break. Keep QFAPI updated to the latest version for your Minecraft version.

How to Read a Quilt Crash Log

When Minecraft crashes, it generates a crash report. These can look intimidating, but there are a few key things to look for:

• Crash report location: .minecraft/crash-reports/ for full crash reports, or .minecraft/logs/latest.log for the most recent game log
• "Missing dependency" — means a required mod or library is not installed. The log usually names the missing dependency.
• "Incompatible mod" — means a mod detected a version conflict. Check which mods are mentioned.
• "Mixin apply failed" or "mixin conflict" — means two mods are trying to modify the same code. Identify the mods mentioned and check for known incompatibilities.
• "Unsatisfied dependency on fabric-api" — means QFAPI is not installed or is the wrong version.

If you cannot interpret the crash log yourself, copy the full text — it is useful when asking for help.

When to Ask for Help

If none of the fixes above resolve your issue, here is where to get help:

• Quilt Discord — the official Quilt community has support channels where you can share crash logs and get help from experienced users
• Mod's GitHub Issues — if the problem is with a specific mod on Quilt, the mod's GitHub repository is the best place to report it. Include your crash log and list of installed mods.
• Modrinth comments — some mod authors respond to compatibility reports on their Modrinth pages

When asking for help, include: your Minecraft version, Quilt Loader version, QFAPI version, a list of all installed mods, and the full crash log.

For comparison with Fabric-specific issues, see our Fabric Mods Not Working guide — many of the same principles apply.

Other Mod Loader Guides

Having trouble with a different mod loader? Check out these troubleshooting guides:

• Forge Mods Not Working?
• Fabric Mods Not Working?
• NeoForge Mods Not Working?
• Fabric vs Quilt — Fabric's community fork explained

Frequently Asked Questions

Why do my Fabric mods not work on Quilt?

The most common reason is that Quilted Fabric API (QFAPI) is not installed. QFAPI is the compatibility layer that allows Fabric mods to run on Quilt. Without it, Fabric mods have nothing to hook into. Download QFAPI from Modrinth and place it in your mods folder.

Do I need both Fabric API and QFAPI?

No. When using Quilt, you only need QFAPI. Quilted Fabric API already includes Fabric API compatibility. Installing both can actually cause conflicts and crashes. If you switched from Fabric to Quilt, remove the standalone Fabric API jar from your mods folder.

How do I report a Quilt bug?

If you believe the issue is with Quilt Loader itself (not a specific mod), you can report it on the Quilt project's GitHub repositories. For mod-specific issues on Quilt, report to the mod's own issue tracker and mention that you are using Quilt with QFAPI. Including your crash log and mod list helps developers diagnose the problem.

Should I switch to Fabric if mods keep breaking on Quilt?

If you are experiencing repeated compatibility issues, switching to Fabric is a reasonable option. Since most of the mods you use on Quilt are Fabric mods running through a compatibility layer, using Fabric directly eliminates that extra layer and may resolve edge-case issues. The switch is straightforward — install Fabric Loader, replace QFAPI with Fabric API, and your mods should work as before.