> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.simplyprint.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Why won't my filament color match a printer?

# Why won't my filament color match a printer?

Color is the number-one reason a queue item won't match a printer, and it's the one that confuses people most - a printer is loaded with what looks like the right color, but the item still won't start. This guide is the complete reference: how SimplyPrint actually decides whether two colors match, the strictness setting that controls it, the two tools that fix a mismatch (**color clusters** and **color mapping**), and when to reach for each.

|| Color matching drives queue and AutoPrint auto-matching, which are part of the Pro plan and up. The color clusters, color mapping and palette tools are available to all plans. See [pricing](https://simplyprint.io/pricing).

If you're troubleshooting a stuck queue item in general (not just color), start with [why won't my printer print this queue item?](https://help.simplyprint.io/en/article/why-wont-my-printer-print-this-queue-item-using-the-queue-inspector-1ue6woy/) and come back here for the color detail.

## In this article
- [The short version](#2-the-short-version)
- [How color matching actually works](#2-how-color-matching-actually-works)
- [The strictness setting: "Material colors must match"](#2-the-strictness-setting-material-colors-must-match)
- [Worked examples: what matches and what doesn't](#2-worked-examples-what-matches-and-what-doesnt)
- [Fix 1: color clusters (treat colors as equivalent)](#2-fix-1-color-clusters-treat-colors-as-equivalent)
- [Fix 2: color mapping (rewrite one color to another)](#2-fix-2-color-mapping-rewrite-one-color-to-another)
- [Clusters vs mapping: which one do I want?](#2-clusters-vs-mapping-which-one-do-i-want)
- [Material type matters too (and material clusters)](#2-material-type-matters-too-and-material-clusters)
- [Where a color comes from: auto-tagging and the palette](#2-where-a-color-comes-from-auto-tagging-and-the-palette)
- [Settings quick reference and defaults](#2-settings-quick-reference-and-defaults)
- [Related articles](#2-related-articles)

## The short version
- SimplyPrint matches color on the **actual color** - both the color **name** and the **hex** code - not just the name.
- How close is "close enough" is set by **Material colors must match** (in your queue / AutoPrint matching criteria). The default is **Similar match**.
- Fix a stubborn mismatch two ways: a **color cluster** (declare two colors equal - works both directions, and even at the strictest setting) or a **color mapping** (rewrite one color into another when files are tagged).
- "Material shrinkage" is a *slicer* setting for dimensional accuracy. It has nothing to do with color matching - if you came here about that, it won't help.

## How color matching actually works
Every queue item that's tagged with a color carries two pieces of information: a color **name** (like "Red") and a **hex** code (like `#D50000`). The printer's loaded spool carries the same two pieces. When SimplyPrint checks whether the printer can run the item, it compares the colors - and it does not just compare the names.

![Color matching compares both the color name and the hex; two reds with different hex codes are a mismatch until you bridge them with a color cluster or a color mapping](https://storage.crisp.chat/users/helpdesk/website/-/f/f/2/2/ff22a914001c1000/filament-color-matching-color-_vfxcbd.png)

There's one important split in how strict that comparison is:

- **On a single-material printer**, the check is strict: the color matches only when the **name** and the **hex** both agree (or a color cluster says they're equal). Two spools both called "red" with different hex codes are treated as different colors.
- **On a printer with a multi-material system** (Bambu Lab AMS, Prusa MMU, Creality CFS, Anycubic ACE), SimplyPrint builds a color map to assign each of the file's colors to a loaded slot. That mapping can be smarter - it can treat near-identical colors as the same by resolving each to its nearest named color - and *how* smart is exactly what the strictness setting below controls.

Either way, clearly different colors never match on their own, and you bridge a deliberate near-miss with a color cluster or a color mapping.

## The strictness setting: "Material colors must match"
In your matching criteria (**Settings › Print queue**, and separately **Settings › AutoPrint**) there's a dropdown labelled **Material colors must match**, with the help text "Select the level of precision to use when matching colors." It has five levels, from strictest to loosest:

| Level | What SimplyPrint does |
| --- | --- |
| **Exact match** | Colors must have identical names or HEX codes. |
| **Close match** | Matches identical color names, or very close colors. |
| **Similar match** (default) | Matches colors in the same color family - e.g. "Dark Blue" matches "Navy". |
| **Flexible match** | Permits loose fallback strategies (useful for single-material printers). |
| **Any color** | Catch-all: if no match is found, any available material is accepted. |

![The color strictness spectrum from Exact match to Any color, with the default at Similar match](https://storage.crisp.chat/users/helpdesk/website/-/f/f/2/2/ff22a914001c1000/filament-color-matching-color-_1ij0i9d.png)

|| Important nuance: the middle levels (Close, Similar, Flexible) only really change behaviour on **multi-material** printers, where SimplyPrint scores how close two colors are. On a **single-material** printer there's no such scoring, so Exact through Flexible all behave the same - a strict name/hex check - and only **Any color** loosens it (accepting any loaded filament). So on single-material printers, think of this setting as "colors must match" vs "any color", and use **clusters** to make specific colors count as equal.

**When to use which:**
- **Exact match** - color-critical work where the wrong shade is a reject (production farms printing to a spec). Combine with clusters for the handful of colors you treat as interchangeable.
- **Similar match** (default) - the right choice for almost everyone. It stops a free printer sitting idle just because "Navy" and "Dark Blue" are named differently, while still refusing to print your red part in green.
- **Any color** - when color genuinely doesn't matter (prototypes, jigs, internal parts) and you just want the queue to use whatever's loaded. This effectively turns the color check off.

This dropdown is one of a whole set of matching-criteria toggles (nozzle, bed, material type, size, temperatures). For the full list, defaults, and a strict-vs-loose workflow across all of them, see [why won't my printer print this queue item?](https://help.simplyprint.io/en/article/why-wont-my-printer-print-this-queue-item-using-the-queue-inspector-1ue6woy/#2-how-strict-is-matching-the-criteria-settings).

## Worked examples: what matches and what doesn't
All examples assume default settings (Similar match) unless noted.

| Item needs | Printer has | Result | Why |
| --- | --- | --- | --- |
| Red `#D50000` | Red `#D50000` | Matches | Identical name and hex. |
| Red `#D50000` | Red `#E30022` | No match (single-material) | Same name, different hex - treated as different colors. Fix with a cluster. |
| Dark blue | Navy | Matches (multi-material) | Same color family at Similar match. On single-material, add a cluster. |
| Blue PLA | Blue PETG | Color matches, but the item may still miss | Color is fine; the mismatch is now **material type** (PLA vs PETG). See below. |
| Red | (nothing loaded / unknown) | No match | The printer has no loaded or tagged color to compare against. Load a spool or assign one. |
| Red, set to **Any color** | Green | Matches | "Any color" accepts whatever is loaded. |
| Red (in a cluster with Crimson) | Crimson | Matches | The cluster declares them equal - works even at Exact match. |

The [queue inspector](https://help.simplyprint.io/en/article/why-wont-my-printer-print-this-queue-item-using-the-queue-inspector-1ue6woy/) shows this as the **Color** reason on any printer that's excluded, so you never have to guess which of these you've hit.

## Fix 1: color clusters (treat colors as equivalent)
A color cluster is a group of colors you've declared interchangeable. When one color in a cluster is detected on a file, **every other color in that cluster is also accepted** as a match. Clusters are the right fix when several colors should always count as the same working color - three brands of black, "Natural" and "White", or a set of near-identical reds.

Two things make clusters powerful:
- They work **both directions** - membership is equivalence, not a one-way rule.
- They count as an **exact** match, so a cluster bridges colors **even when your strictness is set to Exact match**. Tighten the global setting, keep your handful of known-equivalents flowing.

**How to build one** (**Settings › Tagging › Colors › Color clusters**):
1. Click **Add color cluster**. Each cluster needs at least **2** colors.
2. For each entry, set a color. You have three ways:
   - Type a **hex** and/or a **color name** by hand.
   - Pick from the palette swatches.
   - Use **Import colors** / **Get color from...** to pull real colors from a source (see below).
3. Optionally set a **specific material** on an entry ("Optional specific material") so the equivalence only applies to that material - e.g. cluster these two reds only for PLA. Leave it blank to apply to any material.
4. Save. Clusters apply everywhere colors are matched - the queue, AutoPrint, the control panel and the file selector.

**The "Get color from..." sources** (the "select from a file / a printer" part). Instead of typing hex codes, pull the exact colors that already exist in your setup:
- **Filament database** - pick a brand and material to grab its colors from the Open Filament Database.
- **A printer** - grab a color currently set on one of a printer's slots, including colors the printer itself reported that don't have a name yet.
- **A file** - grab a file's tagged colors, plus the raw colors detected inside the file.

That last two are the fix for the most common real cause of a mismatch: the color your slicer baked into the file has a slightly different hex than the color on your spool. Grab both (one from **A file**, one from **A printer**), drop them in a cluster, and they'll match from now on.

|| Shortcut: when the queue inspector flags a color mismatch, opening the **Color matching** modal offers to build the exact cluster for you - it pre-fills the file's color and the printer's color as a suggested pair. One click and the two are equal.

## Fix 2: color mapping (rewrite one color to another)
A color mapping is a **one-directional rewrite**: "whenever a file is tagged as color A, store it as color B instead." As the panel puts it, you can map "Red" to "Crimson", optionally only for a specific material. Unlike a cluster, a mapping actually **changes the color stored on the item** - it's applied when the file is auto-tagged, not at match time.

Build one at **Settings › Tagging › Colors › Color mapping**: set the **From** color (a hex, optionally scoped to a material) and the **To** color (hex + name). Mapping is the right tool when a slicer or profile keeps producing a color you'd rather standardise on - you're normalising your data at the source, so everything downstream lines up.

## Clusters vs mapping: which one do I want?
They solve the same symptom differently, and the distinction matters:

![A color cluster makes two colors count as equal at match time; a color mapping rewrites one color into another when a file is tagged](https://storage.crisp.chat/users/helpdesk/website/-/f/f/2/2/ff22a914001c1000/filament-color-matching-cluste_1bsk6s9.png)

| | Color cluster | Color mapping |
| --- | --- | --- |
| What it does | Declares colors **equivalent** for matching | **Rewrites** one color into another |
| Direction | Both ways (A = B) | One way (A becomes B) |
| When it applies | At **match time** (compares item to printer) | At **auto-tag time** (when a file is added) |
| Changes stored data? | No | Yes - the item's color is replaced |
| Best for | "These colors all count as the same" | "Always store this color as that one" |

Rule of thumb: reach for a **cluster** first (it's non-destructive and bidirectional). Use a **mapping** when you specifically want to clean up incoming color data so it's consistent everywhere.

## Material type matters too (and material clusters)
Color is only half of "material". A queue item can match on color and still be excluded because the **material type** is wrong - blue PLA won't run on a printer loaded with blue PETG. Two related controls:

- **Strict material type match** (on by default) - "Use branded material types rather than generic. Generic PLA will not match with Bambu Lab PLA Basic if this setting is enabled." Turn it off to match at the family level (any PLA matches any PLA). This defaults to strict for a good reason: branded materials genuinely differ - in temperatures, flow, density and even shrinkage - so treating them as identical can hurt a print.
- **Material clusters** - the material equivalent of color clusters. Declare two material types equal (your house-brand PLA and PLA+) so they match each other. Set them up in **Settings › Tagging › Materials**.

|| "Material shrinkage" is a **slicer** setting (it scales the model to compensate for filament contracting as it cools) - it lives in your filament profile, not in matching, and it has **no effect on color matching**. If someone told you color is "affected by material shrinking", that's a mix-up: the levers that affect color matching are the strictness setting, clusters, and mapping - nothing else.

## Where a color comes from: auto-tagging and the palette
Most items get their color automatically when they're sliced or added - **auto-tagging** reads the file and applies a color name and hex. If items are consistently getting the wrong color, the fix is upstream in your tagging rules rather than per-item. Two settings shape what color gets recorded:

- **Single-color files** - by default, a single-color file is tagged with its material type but **no color** (the assumption is it's the default color, not a color-specific job). If you want single-color files to carry their color too, enable "Auto-tag color on single-extrusion files" in **Settings › Tagging**.
- **The color picker palette** (**Settings › Tagging › Colors › Color picker palette**) - controls which colors are offered when assigning colors. Five modes: **Standard palette** (default - standard + your custom + brand colors), **Custom palette only**, **Filament inventory** (only colors of spools you own), **Loaded filament only**, and **Loaded color tags only** (strictest). Two optional locks go with it: **Lock selection to the palette** (hide the "add custom color" option) and **Don't auto-tag colors outside the palette** (drop a detected color that isn't in your palette; this one only appears once you pick a non-standard palette mode). Both are **off** by default.

For the full auto-tagging picture, see [auto-tagging and auto printer-model selection](https://help.simplyprint.io/en/article/auto-tagging-auto-printer-model-selection-e84r3k/). For per-slot color on multi-material printers, see [multi-material color mapping](https://help.simplyprint.io/en/article/multi-material-mapping-bambu-lab-ams-support-1d57m9j/).

## Settings quick reference and defaults
Everything that affects color matching, and where to find it:

| Setting | Default | Where | What it does |
| --- | --- | --- | --- |
| Material colors must match | Similar match | Settings › Print queue (and AutoPrint) | How strict the color comparison is |
| Color clusters | none | Settings › Tagging › Colors | Declare colors equivalent |
| Color mapping | none | Settings › Tagging › Colors | Rewrite one color into another |
| Strict material type match | On | Settings › Print queue (and AutoPrint) | Branded vs generic material matching |
| Material clusters | none | Settings › Tagging › Materials | Declare materials equivalent |
| Color picker palette | Standard palette | Settings › Tagging › Colors | Which colors the picker offers |
| Lock selection to the palette | Off | Settings › Tagging › Colors | Hide off-palette color entry |
| Don't auto-tag colors outside the palette | Off | Settings › Tagging › Colors | Drop detected off-palette colors |
| Auto-tag color on single-extrusion files | Off | Settings › Tagging | Keep color on single-color files |

## Related articles
- [Why won't my printer print this queue item?](https://help.simplyprint.io/en/article/why-wont-my-printer-print-this-queue-item-using-the-queue-inspector-1ue6woy/)
- [All about the "Tags" feature](https://help.simplyprint.io/en/article/all-about-the-tags-feature-mwvsst/)
- [Auto-tagging and auto printer-model selection](https://help.simplyprint.io/en/article/auto-tagging-auto-printer-model-selection-e84r3k/)
- [Multi-material color mapping](https://help.simplyprint.io/en/article/multi-material-mapping-bambu-lab-ams-support-1d57m9j/)
- [Auto-matching queue items to printers](https://help.simplyprint.io/en/article/auto-matching-queue-items-to-printers-xdn526/)