Installation, Initialization & Environments

Initialization fails with type/runtime errors when config values have the wrong shape (for example, passing a string where an object is expected).

Root Cause
Initialization parameters do not match the expected data types (e.g., passing stringified JSON instead of a raw object), or Marketplace app configuration schemas are misaligned with defined parameter shapes.

Resolution

1. Validate the SDK initialization object against the SDK README/types.
2. Ensure nested options (proxy/retry/cache/plugin options) are objects, not stringified JSON.
3. For Marketplace apps, verify config schema matches app parameter definitions.

SDK initializes without exception and the first API call returns a 2xx JSON response. Escalate with a redacted config object and full stack trace if error persists.

Runtime/module parse errors can occur when project Node runtime is incompatible with package expectations.

Root Cause
The project's Node.js runtime version falls outside the supported range of the specific SDK or CLI package, causing syntax errors or module parsing failures during execution.

Resolution

1. Check node -v.
2. Use an Active LTS Node version unless the specific SDK/CLI package documents different requirements.
3. Reinstall dependencies after runtime switch.
4. Avoid blanket downgrade guidance. Align Node version per package constraints in your lockfile/CI.

Install/import completes and sample SDK calls run without syntax/module loader errors.

SSR builds/runtime can fail when browser-only assumptions leak into server execution paths.

Resolution

1. Initialize SDK with contentstack.stack(...) in server-safe modules.
2. Keep browser-only logic behind typeof window !== 'undefined' checks.
3. Pass explicit environment/region in config for deterministic server behavior.
4. Avoid older constructor/global-singleton patterns in SSR code.

Server render completes and fetch returns 2xx without window is not defined or similar runtime errors. Escalate with framework version and minimal initialization snippet.

The SDK fails to initialize or connect with "Undefined" values because it cannot successfully read the API Key or Token from local .env files.

Root Cause
The SDK is imported or initialized before the application has finished loading .env files, or there is a naming mismatch between the system environment keys and the code.

Resolution

1. Load env variables before any SDK initialization/import side effects.
2. Match env key names exactly between .env and code.
3. Restart runtime after changing .env.

Startup shows non-empty required env vars (redacted), and the first SDK call returns 2xx. Escalate with startup order snippet and SDK version if envs are present but init still fails.

Browser runtime errors occur when Node-only globals/modules are pulled into client bundles.

Root Cause
The application is attempting to use Node.js-specific modules (like Buffer) in a client-side browser environment without the necessary polyfills or the use of a browser-safe SDK build.

Resolution

1. Upgrade to the latest supported SDK/browser-safe package build.
2. Remove Node-only imports from client-side bundles.
3. Add polyfills only when upgrade/refactor is not immediately possible.

Browser flow completes without Buffer being defined, and SDK calls return expected data. Escalate with bundler config and import graph if error persists.

Installing the SDK results in a "Peer Dependency Conflict," preventing installation in projects using specific versions of React or Node.

Root Cause
Version mismatches between the SDK’s requirements and the existing project dependencies (e.g., React or Node.js versions) prevent the package manager from resolving a stable dependency tree.

Resolution

Install failures often come from incorrect package names or incompatible dependency trees.

1. Install correct SDK packages for the use case:
   • @contentstack/delivery-sdk
   • @contentstack/management
2. Align Node and package manager versions with project/toolchain constraints.
3. Resolve lockfile conflicts explicitly; use bypass flags only as a temporary debugging step.

npm i @contentstack/delivery-sdk
npm i @contentstack/management

Packages install successfully and import without unresolved dependency conflicts. Escalate with lockfile excerpt, package manager version, and full install error output.