Contentstack JavaScript Delivery SDK

Common errors

• TypeError: Contentstack is not a function

  cause Attempting to import `Contentstack` as a named export (`import { Contentstack } from 'contentstack';`) when it's a default export, or trying to directly call `Contentstack()` as a constructor when `Contentstack.Stack()` is the correct method for initialization.
  fix Use the correct default import: `import Contentstack from 'contentstack';` and then initialize with `Contentstack.Stack({...});`.

• Contentstack: api_key, delivery_token or environment is missing

  cause The SDK initialization object is missing one or more of the required `api_key`, `delivery_token`, or `environment` parameters.
  fix Ensure all three required parameters (`api_key`, `delivery_token`, and `environment`) are provided in the object passed to `Contentstack.Stack()`.

• ReferenceError: Contentstack is not defined

  cause In a browser environment, the Contentstack SDK script tag was not loaded, or the variable is being accessed before the script has executed and defined it globally. In Node.js, the import statement might be missing or incorrect.
  fix For browsers, ensure `<script src="https://cdn.jsdelivr.net/npm/contentstack@latest/dist/web/contentstack.min.js"></script>` is loaded before usage. For Node.js/ESM, ensure `import Contentstack from 'contentstack';` is at the top of your file.

• Error: Request failed with status code 401 (Unauthorized)

  cause The provided `api_key` or `delivery_token` is incorrect, expired, or does not have permissions to access the specified environment or content.
  fix Verify that your `api_key`, `delivery_token`, and `environment` are correct and have the necessary permissions in your Contentstack account. Ensure you are using a Delivery Token for content fetching.

• UND_ERR_SOCKET

  cause Unhandled socket errors occurring during network connection drops, leading to process termination in older SDK versions.
  fix Upgrade the `contentstack` SDK to version `3.27.0` or higher to benefit from the fix for connection drop handling.

Warnings

• breaking A security vulnerability (CVE-2025-15284) related to the 'qs' dependency was fixed in `v3.26.4`. Prior versions are affected.
  Fix: Upgrade to `contentstack@3.26.4` or higher to mitigate the 'qs' dependency vulnerability.
• gotcha Applications using `contentstack` versions prior to `3.27.0` may experience process crashes due to unhandled socket errors (`UND_ERR_SOCKET`) during network connection drops.
  Fix: Upgrade to `contentstack@3.27.0` or higher to ensure robust handling of connection drops and prevent process termination.
• gotcha The SDK requires Node.js version 10.14.2 or higher. Running on older Node.js environments may lead to unexpected errors, initialization failures, or runtime crashes. The TypeScript Delivery SDK specifically recommends Node.js 22 or later.
  Fix: Ensure your Node.js environment meets the minimum requirement of 10.14.2, and ideally use 22 or later for TypeScript projects.
• gotcha Failing to correctly specify the region (e.g., `Contentstack.Region.EU`, `Contentstack.Region.AU`, `Contentstack.Region.AZURE_NA`, `Contentstack.Region.GCP_EU`) during SDK initialization can result in content fetching failures or increased latency if the default North American region is not desired.
  Fix: Initialize the SDK with the correct `region` parameter, for example: `Contentstack.Stack({... "region": Contentstack.Region.EU });`
• breaking The underlying Contentstack platform has deprecated Access Tokens for stacks created after December 16, 2020. While older stacks still support them, new stacks require Delivery Tokens for content fetching via the Delivery API.
  Fix: For new Contentstack stacks (created after Dec 16, 2020), always use Delivery Tokens instead of Access Tokens. Update your SDK initialization to use `delivery_token`.

Install

• npm install contentstack npm
• yarn add contentstack yarn
• pnpm add contentstack pnpm

Imports

• Contentstack
  wrong:

  import { Contentstack } from 'contentstack';

  correct:

  import Contentstack from 'contentstack';

  This is the primary default export for the SDK. For CommonJS, `const Contentstack = require('contentstack');` is typically used and correctly returns the default export.
• Stack
  wrong:

  import { Stack } from 'contentstack';

  correct:

  import Contentstack from 'contentstack'; const Stack = Contentstack.Stack({ ... });

  The `Stack` initialization method is accessed as a property of the default `Contentstack` export, not a named export itself.
• Region (Enum)
  wrong:

  import { Region } from 'contentstack';

  correct:

  import Contentstack from 'contentstack'; Contentstack.Region.EU;

  Region enum values (e.g., EU, AU, AZURE_NA, GCP_EU) are properties of the default `Contentstack` export, used for configuring the delivery region during SDK initialization.

Quickstart

This quickstart demonstrates how to initialize the Contentstack SDK and fetch a single entry by its content type UID and entry UID. It includes essential error handling for missing credentials and showcases region configuration.

import Contentstack from 'contentstack';

const API_KEY = process.env.CONTENTSTACK_API_KEY ?? '';
const DELIVERY_TOKEN = process.env.CONTENTSTACK_DELIVERY_TOKEN ?? '';
const ENVIRONMENT = process.env.CONTENTSTACK_ENVIRONMENT ?? '';
const CONTENT_TYPE_UID = 'blog'; // Replace with your content type UID
const ENTRY_UID = 'your_entry_uid'; // Replace with a specific entry UID

if (!API_KEY || !DELIVERY_TOKEN || !ENVIRONMENT) {
  console.error('Missing Contentstack credentials. Please set CONTENTSTACK_API_KEY, CONTENTSTACK_DELIVERY_TOKEN, and CONTENTSTACK_ENVIRONMENT environment variables.');
  process.exit(1);
}

const Stack = Contentstack.Stack({
  api_key: API_KEY,
  delivery_token: DELIVERY_TOKEN,
  environment: ENVIRONMENT,
  // Optional: Set a specific region, e.g., for Europe
  // region: Contentstack.Region.EU 
});

async function fetchEntry() {
  try {
    const query = Stack.ContentType(CONTENT_TYPE_UID).Entry(ENTRY_UID);
    const entry = await query.toJSON().fetch();
    console.log('Fetched Entry Title:', entry.get('title'));
    console.log('Entry content:', entry.toJSON());
  } catch (error) {
    console.error('Error fetching entry:', error);
  }
}

fetchEntry();