Ky HTTP Client

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES Module `import` syntax in a CommonJS environment or an older Node.js version that does not support ESM without explicit configuration.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and you are using Node.js 22 or higher. Alternatively, ensure your bundler properly transpiles ESM.

• TypeError: ky.post is not a function

  cause Ky was not imported correctly, or the `ky` variable is `undefined`/`null`, often due to an incorrect import path or using `require()` for an ESM-only package.
  fix Verify your import statement: `import ky from 'ky';`. Confirm your environment supports ESM and Ky's Node.js version requirement.

• HTTPError: Not Found (404)

  cause The requested resource was not found on the server. Ky automatically throws an `HTTPError` for any non-2xx status code.
  fix Check the URL, `prefix` option, and any `searchParams` for correctness. Handle `HTTPError` in your `try...catch` block to manage API errors gracefully.

• TypeError: Cannot read properties of undefined (reading 'headers') in Ky hook

  cause A Ky hook function, like `beforeRequest`, is attempting to access properties of its second argument (e.g., `options`), but the hook signature changed in v2 to expect a single state object, making subsequent arguments `undefined`.
  fix Update your hook signature. For example, change `(request, options) => { console.log(options.headers); }` to `({request, options}) => { console.log(options.headers); }`.

• Failed to construct 'URL': Invalid URL

  cause After upgrading to Ky v2, the `prefixUrl` option was used, but it has been renamed to `prefix`. Ky did not apply the base URL, leading to an invalid or relative URL being passed to `fetch`.
  fix Rename `prefixUrl` to `prefix` in your Ky options. Ensure that `input` is a valid relative path if relying on the `prefix` option for the base URL.

Warnings

• breaking Ky v2.0.0 and later require Node.js 22 or newer.
  Fix: Upgrade your Node.js environment to version 22 or higher. For older Node.js versions, use Ky v1.x.
• breaking All Ky hooks (e.g., `beforeRequest`, `afterResponse`, `beforeError`) now receive a single state object (`{request, options, retryCount, ...}`) instead of separate arguments.
  Fix: Update your hook functions to destructure the state object. For example, change `(request, options) => { ... }` to `({request, options}) => { ... }`.
• breaking The `prefixUrl` option has been renamed to `prefix`.
  Fix: Replace `prefixUrl: '...'` with `prefix: '...'` in your Ky options.
• gotcha Unlike plain `fetch`, Ky automatically throws an `HTTPError` for non-2xx status codes (e.g., 404 Not Found, 500 Internal Server Error) after redirects. This behavior is enabled by default.
  Fix: Wrap your Ky calls in a `try...catch` block to handle `HTTPError` for non-successful responses. To disable this behavior, set `throwHttpErrors: false` in your options.
• gotcha The `.json()` shortcut method throws an error if the response body is empty or the HTTP status is 204 No Content, as it expects valid JSON content.
  Fix: Ensure your API returns a valid JSON body for endpoints where you use `.json()`. For 204 responses or empty bodies, use `.text()` or handle the error in a `try...catch` block.

Install

• npm install ky npm
• yarn add ky yarn
• pnpm add ky pnpm

Imports

• ky

  import ky from 'ky';

  Ky is an ESM-only package and requires Node.js 22+ since v2.

Quickstart

Demonstrates making a POST request with JSON payload to an example URL and logging the parsed JSON response.

import ky from 'ky';

const exampleJson = await ky.post('https://example.com', {
  json: { foo: true },
}).json();

console.log(exampleJson);
// => {data: '🦄'}