# incompatible_units

> convert received two units it can't convert between, such as cups and grams, or a count with no fixed size, such as a clove or a quantity without a unit.

Source: https://recipe-book.siraj.page/errors/incompatible_units/

[`convert`](https://recipe-book.siraj.page/reference/core/units.md#convert) received two units it can't convert between: one measures volume and the other mass, such as cups and grams, or one is a count with no fixed size, such as `clove` or a quantity without a unit.

```txt
RecipeBookError: Cannot convert cup (volume) to g (mass). Add an equivalent to the ingredient, e.g. equivalents: ["120 g"].
See https://recipe-book.siraj.page/errors/incompatible_units/
```

A cup of flour and a cup of sugar weigh different amounts, so converting volume to mass needs a density that only the recipe author knows.

| Received                  | Message                                                                                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Volume and mass           | `Cannot convert cup (volume) to g (mass). Add an equivalent to the ingredient, e.g. equivalents: ["120 g"].`                                                        |
| Mass and volume           | `Cannot convert g (mass) to cup (volume). Add an equivalent to the ingredient, e.g. equivalents: ["250 ml"].`                                                       |
| A count unit              | `Cannot convert clove to g; clove is a count unit with no fixed size. Add an equivalent to the ingredient, e.g. equivalents: ["120 g"].`                            |
| Mass and a count unit     | `Cannot convert oz to piece; piece is a count unit with no fixed size. Add an equivalent to the ingredient, e.g. equivalents: ["1 piece"].`                         |
| A quantity without a unit | `Cannot convert a quantity without a unit to g; a bare count such as "2 eggs" has no fixed size. Add an equivalent to the ingredient, e.g. equivalents: ["120 g"].` |

## Units by dimension

Units convert only to units of the same dimension, and count units only to themselves:

| Dimension | Unit IDs                                                                                                                          |
| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Mass      | `mg`, `g`, `kg`, `oz`, `lb`                                                                                                       |
| Volume    | `ml`, `cl`, `dl`, `l`, `tsp`, `tbsp`, `tbsp-au`, `fl-oz`, `cup`, `cup-metric`, `pint`, `quart`, `gallon`                          |
| Count     | `pinch`, `dash`, `clove`, `slice`, `piece`, `can`, `package`, `stick`, `sprig`, `bunch`, `head`, `bag`, `handful`, `jar`, `stalk` |

The [unit registry](https://recipe-book.siraj.page/reference/core/units.md#units) lists each unit's size and the aliases [`findUnit`](https://recipe-book.siraj.page/reference/core/units.md#findunit) accepts.

## Add an equivalent to the ingredient

The message suggests an equivalent: a quantity the author supplies for an ingredient in recipe input, such as `equivalents: ['190 g']` for 1 ½ cups of flour. The quantity in the message is a placeholder, not a conversion.

With that equivalent, [`resolveRecipe`](https://recipe-book.siraj.page/reference/core/resolving.md#resolverecipe) in the metric system shows the flour as 190 g instead of converting the cups to milliliters.

## Convert to a measurement system instead

To show a US recipe in metric units, you don't need grams. [`toSystem`](https://recipe-book.siraj.page/reference/core/units.md#tosystem) converts to a metric unit of the same dimension:

```ts
import { toSystem } from '@recipe-book/core'

toSystem({ amount: 1.5, unit: 'cup' }, 'metric') // { amount: 354.88235475, unit: 'ml' }
```

## Check units before converting

Quantities from data can hold any unit, or none, and `convert` throws for one without a unit:

```ts {7}
import { convert, type Quantity } from '@recipe-book/core'

function toGrams(quantity: Quantity) {
  return convert(quantity, 'g')
}

toGrams({ amount: 2 })
```

Check with [`canConvert`](https://recipe-book.siraj.page/reference/core/units.md#canconvert) first, and keep quantities it rejects as they are:

```ts {4}
import { canConvert, convert, type Quantity } from '@recipe-book/core'

function toGrams(quantity: Quantity) {
  if (!canConvert(quantity.unit, 'g')) return quantity
  return convert(quantity, 'g')
}

toGrams({ amount: 1, unit: 'lb' }) // { amount: 453.59237, unit: 'g' }
toGrams({ amount: 2 }) // { amount: 2 }
```
