> For AI agents: the complete documentation index is available at https://massaman.dev/llms.txt, the full documentation bundle is available at https://massaman.dev/llms-full.txt.

# err

Constructs a failure [`Result`](https://massaman.dev/concepts/result.md). Preserves specific `Error` types and normalizes non-Error values into `Error`.

```typescript
const result = err(reason)
```

## Usage

### `err(reason)`

Pass an `Error`, a string, or any other value. `Error` instances are returned unchanged, including their specific subtype. Strings are wrapped in `new Error(reason)`. Non-error, non-string values get `JSON.stringify`'d into the message and the original is preserved on `error.cause`.

```typescript
import { err } from 'massaman'

err(new Error('boom'))
// { ok: false, value: null, error: Error('boom') }

err('division by zero')
// { ok: false, value: null, error: Error('division by zero') }

err({ code: 'EBADF', fd: 3 })
// { ok: false, value: null, error: Error('{"code":"EBADF","fd":3}', { cause: { code: 'EBADF', fd: 3 } }) }
```

Use `createError` or `defineError` when callers need typed custom data:

```typescript
import { createError, err, type ErrorWith } from 'massaman'

type NotFound = ErrorWith<'NotFound', { readonly specId: string }>

const error = createError<NotFound>({
  name: 'NotFound',
  message: 'Spec not found',
  specId: 'spec-1',
})

const result = err(error)
// Err<NotFound>
```

#### Parameters


reasonunknownrequired

the failure value. Accepts anything — normalization to `Error` is the function's job.

#### Returns

`Err<E>` when given `E extends Error`; otherwise `Err<Error>`.

```typescript
Err<E>
```

## See also

- [`ok`](https://massaman.dev/reference/control/ok.md) — construct a success result
- [`attempt`](https://massaman.dev/reference/control/attempt.md) — wrap an unsafe call
- [`createError`](https://massaman.dev/reference/error/createError.md) and [`defineError`](https://massaman.dev/reference/error/defineError.md) — construct typed native errors
- [Result & Errors concept guide](https://massaman.dev/concepts/result.md)
