# invalid_quantity

> parseQuantity found a problem in quantity text, such as '2 cupz', and the error's issue says what it is.

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

[`parseQuantity`](https://recipe-book.siraj.page/reference/core/parsing.md#parsequantity) found a problem in quantity text. It returns a [`RecipeValidationError`](https://recipe-book.siraj.page/reference/core/errors.md#recipevalidationerror) with the code `invalid_quantity` in `result.error`, and the error's `issues` hold one issue.

```txt
RecipeValidationError: "2 cupz" has 1 problem:
  ✖ (root)  Unknown unit "cupz". Did you mean "cups"?
See https://recipe-book.siraj.page/errors/invalid_quantity/
```

The text is the whole input, so the issue's path is empty, which the message writes as `(root)`.

The issue's code names the problem: here, [`unknown_unit`](https://recipe-book.siraj.page/errors.md#issue-unknown_unit). As an issue code, [`invalid_quantity`](https://recipe-book.siraj.page/errors.md#issue-invalid_quantity) means the parser couldn't read the text. [Issue codes](https://recipe-book.siraj.page/errors.md#issue-codes) explains each one. In recipe input, the same problems are issues in an [`invalid_recipe`](https://recipe-book.siraj.page/errors/invalid_recipe.md) error, at the quantity's path, along with [the issues below](https://recipe-book.siraj.page/errors/invalid_quantity.md#quantities-in-recipe-input), where text must be from 1e-300 to 1e290.

| Received                             | Issue code                                                                        | Message                                                                                                                               |
| ------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `'2 punnets'`                        | `unknown_unit`                                                                    | `Unknown unit "punnets". Use a known unit, or move the word into the name: { name: "punnets", quantity: 2 }.`                         |
| `'2 tsp salt'`                       | `unknown_unit`                                                                    | `Unknown unit "tsp salt". Keep "tsp" in the quantity and move the rest into the name or note.`                                        |
| `'two cups'`                         | `invalid_quantity`                                                                | `Couldn't read "two cups". Use a number or fraction, e.g. "1 ½ cups".`                                                                |
| `'1,500 g'`                          | `invalid_quantity`                                                                | `Couldn't read "1,500 g". "1,500" could be "1500" or "1.5": write one of those, or pass { decimal: "," } to read commas as decimals.` |
| `'1.500 g'`, with `{ decimal: ',' }` | `invalid_quantity`                                                                | `Couldn't read "1.500 g". "1.500" could be "1500" or "1,5": write one of those.`                                                      |
| `'1,500.5 g'`                        | `invalid_quantity`                                                                | `Couldn't read "1,500.5 g". Leave out thousands separators, e.g. "1500.5".`                                                           |
| `'tbsp'`                             | `invalid_quantity`                                                                | `"tbsp" has no amount. Write a full quantity, e.g. "1 tbsp".`                                                                         |
| `''`                                 | `invalid_quantity`                                                                | `Expected a quantity such as "1 ½ cups", received an empty string.`                                                                   |
| `'0 cups'`                           | [`invalid_amount`](https://recipe-book.siraj.page/errors.md#issue-invalid_amount) | `Expected a positive amount, received "0 cups".`                                                                                      |
| `'3-2 cups'`                         | [`invalid_range`](https://recipe-book.siraj.page/errors.md#issue-invalid_range)   | `Range minimum (3) must not be greater than the maximum (2).`                                                                         |
| `'1-1/2 cups'`                       | `invalid_range`                                                                   | `Range minimum (1) must not be greater than the maximum (1/2). To write a mixed number, use "1 1/2".`                                 |
| A number, `5`                        | [`invalid_type`](https://recipe-book.siraj.page/errors.md#issue-invalid_type)     | `Expected quantity text such as "1 ½ cups", received 5.`                                                                              |

Other values that aren't text get the same message with their own ending, such as `received null.`, `received undefined.`, `received true.`, `received an object.`, or `received an array.` A value that isn't text has no text to quote, so the error's first line names it `Quantity`:

```txt
RecipeValidationError: Quantity has 1 problem:
  ✖ (root)  Expected quantity text such as "1 ½ cups", received 5.
See https://recipe-book.siraj.page/errors/invalid_quantity/
```

A comma is a decimal mark in much of Europe and a thousands separator in the US. A comma between digits that can only be a decimal reads as one with any `decimal`, as in `'1,5 cups'`, but a leading comma, as in `',5 cups'`, is an issue with any `decimal`. With no option, or with `{ decimal: '.' }`, a comma that could be a thousands separator is an issue, as in `'1,000 g'`. With `{ decimal: ',' }`, `'1,000 g'` reads as 1 g, and a period that could be a thousands separator, as in `'1.500 g'`, is an issue instead. A number with two marks, such as `'1,500.5 g'`, is always an issue. See [Read comma decimals](https://recipe-book.siraj.page/errors/invalid_quantity.md#read-comma-decimals).

An amount past about 1.8e308, such as `'9'.repeat(400)`, is too large to read, and so is a fraction whose numerator is past that, even when the fraction's value is smaller. A fraction whose denominator is 0, or whose numerator and denominator are both past 1.8e308, gets "Expected a positive amount" instead at any value, and so does a whole number followed by such a fraction. Text with an amount too large to read gets an `invalid_amount` issue with this message:

```txt
"99999999999999999999999999999999999999999999999999999999999…" has an amount too large to read. Check it for extra digits.
```

## Quantities in recipe input

A quantity in recipe input can also be a number or an `{ amount, unit }` object. [`parseRecipe`](https://recipe-book.siraj.page/reference/core/parsing.md#parserecipe) gives these issues, at the quantity's path, such as `ingredients[0].quantity`, or at its `amount`, `amount.min`, `amount.max`, or `unit`:

| Quantity                           | Issue code                                                                      | Message                                                                                  |
| ---------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `{ unit: 'cup' }`                  | [`missing_field`](https://recipe-book.siraj.page/errors.md#issue-missing_field) | `Add an amount, e.g. { amount: 2, unit: "cup" }.`                                        |
| `{ amount: '2', unit: 'cup' }`     | `invalid_type`                                                                  | `Expected a number or { min, max }, received "2".`                                       |
| `{ amount: { min: 3, max: 2 } }`   | `invalid_range`                                                                 | `Range minimum (3) must not be greater than the maximum (2).`                            |
| `{ amount: { min: 1, max: 'x' } }` | `invalid_type`                                                                  | `Expected a positive number, received "x".`                                              |
| `{ amount: 2, unit: null }`        | `invalid_type`                                                                  | `Expected a unit such as "g" or "cup", received null.`                                   |
| `0`, or `{ amount: 0 }`            | `invalid_amount`                                                                | `Expected a positive number, received 0.`                                                |
| `1e300`, or `{ amount: 1e300 }`    | `invalid_amount`                                                                | `Expected a number from 1e-300 to 1e290, received 1e+300.`                               |
| `null`                             | `invalid_type`                                                                  | `Expected a quantity such as "2 cups", 2, or { amount: 2, unit: "cup" }, received null.` |

## Fix the quantity text

Fix the text as the issue's message says:

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

parseQuantity('2 cupz').success // false
parseQuantity('2 cups') // { success: true, data: { amount: 2, unit: 'cup' }, warnings: [] }
```

## Read comma decimals

When your text writes decimals with a comma, pass `{ decimal: ',' }`:

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

parseQuantity('1,500 g').success // false
parseQuantity('1,500 g', { decimal: ',' }) // { success: true, data: { amount: 1.5, unit: 'g' }, warnings: [] }
```

[`parseRecipe`](https://recipe-book.siraj.page/reference/core/parsing.md#parserecipe) and [`fromJsonLd`](https://recipe-book.siraj.page/reference/core/schema-org.md#fromjsonld) take the same option. [`recipeSchema`](https://recipe-book.siraj.page/reference/core/parsing.md#recipeschema) takes none, so make a schema with [`createRecipeSchema`](https://recipe-book.siraj.page/reference/core/parsing.md#createrecipeschema) instead. [Read regional recipes](https://recipe-book.siraj.page/guides/author-recipes.md#read-regional-recipes) reads a whole recipe this way.

The option reads text only. A quantity object's `amount` is a number, so `{ amount: '1.5', unit: 'cup' }` gets `Expected a number or { min, max }, received "1.5".` with any `decimal`. Write `{ amount: 1.5, unit: 'cup' }` instead.

## Show the problem to authors

The issue's message names the fix, so you can show it next to the field as it is:

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

function quantityError(text: string) {
  const result = parseQuantity(text)
  return result.success ? undefined : result.error.issues[0]?.message
}

quantityError('2 cupz') // 'Unknown unit "cupz". Did you mean "cups"?'
quantityError('2 cups') // undefined
```
