Skip to main content

​
Overview

Constructs an Err variant of Result. This represents a failed computation with an error value.

​
Signature

function err<T = never, E extends string = string>(err: E): Err<T, E>
function err<T = never, E = unknown>(err: E): Err<T, E>
function err<T = never, E extends void = void>(err: void): Err<T, void>

​
Parameters

​
err
E
required
The error value to wrap in an Err result. Can be any type including strings, Error objects, or custom error types.

​
Returns

Returns an Err<T, E> instance containing the provided error value.

​
Examples

​
Basic Usage

import { err } from 'neverthrow'

const myResult = err('Oh noooo')

myResult.isOk() // false
myResult.isErr() // true

​
With Error Objects

const result = err(new Error('Something went wrong'))

if (result.isErr()) {
  console.error(result.error)
}

​
Type Annotations

// Explicitly specify both success and error types
const result = err<number, string>('Invalid input')
// result is Err<number, string>

// With custom error types
type CustomError = { code: number; message: string }
const customErr = err<string, CustomError>({
  code: 404,
  message: 'Not found'
})

​
In Function Returns

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) {
    return err('Cannot divide by zero')
  }
  return ok(a / b)
}

​
Behavior

When a Result is an Err:
  • .isErr() returns true
  • .isOk() returns false
  • Mapping functions like .map() are skipped
  • Error mapping functions like .mapErr() are applied
  • The error value is accessible via .error property (after type narrowing) or ._unsafeUnwrapErr()

Build docs developers (and LLMs) love

Get started for freeTalk to us