Skip to main content

Troubleshooting

Common issues when installing, configuring, and running @cdx-forge/di-typescript-sdk and the cdx-typescript-sdk examples.

CommonJS require() not working​

This package is ESM-only. Your project must use "type": "module" in package.json or .mjs file extensions.

Error [ERR_REQUIRE_ESM]: require() of ES Module ...

Fix: Replace require('@cdx-forge/di-typescript-sdk') with import { CandescentClient } from '@cdx-forge/di-typescript-sdk'.

Cannot find module​

Cannot find module '@cdx-forge/di-typescript-sdk'

Fix:

  1. Run pnpm add @cdx-forge/di-typescript-sdk
  2. Confirm the package appears in package.json dependencies
  3. Delete node_modules and reinstall if the install was interrupted

Authentication errors (401)​

  • Verify CANDESCENT_CLIENT_ID and CANDESCENT_CLIENT_SECRET match the app in the Developer Console
  • Confirm CANDESCENT_INSTITUTION_ID matches the credentials issued to you
  • For staging, set CANDESCENT_ENVIRONMENT=stage (or Environment.Stage in code)
  • If using a static bearer token, ensure it has not expired

See Installation and the Getting Started quickstart guides.

hostUserId and loginId mutually exclusive​

Parameters hostUserId and loginId are mutually exclusive

Pass only one user identifier per request — either hostUserId or loginId, not both.

Examples: module not found​

When running scripts in cdx-typescript-sdk:

Bash
cd cdx-typescript-sdk
pnpm install
node --experimental-strip-types examples/typescript/accounts.ts

Examples: .env not loaded​

Individual example scripts do not auto-load .env. Either:

  • Run source .env before the script, or
  • Use the batch runner: node scripts/run-all-typescript-examples.mjs (loads repo-root .env automatically)

error-handling.ts fails in batch runner​

error-handling.ts is intentionally excluded from run-all-typescript-examples.mjs because it triggers expected API errors. Run it individually:

Bash
node --experimental-strip-types examples/typescript/error-handling.ts

Rate limiting (429)​

The SDK retries 429 responses automatically (up to three attempts). If you still receive RateLimitError, check error.retryAfter and back off before manually retrying.

Top-level await not allowed​

SyntaxError: await is only valid in async functions

Fix: Set "target": "ES2022" and "module": "NodeNext" (or "ESNext") in tsconfig.json, and ensure your project uses ESM ("type": "module" in package.json).

ERR_UNKNOWN_FILE_EXTENSION .ts​

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts"

Fix: Use node --experimental-strip-types file.ts (Node 22+), or run with npx tsx file.ts for older Node versions.

fetch failed / ECONNREFUSED​

  • Confirm CANDESCENT_ENVIRONMENT is set correctly (stage or production)
  • Check that outbound HTTPS (port 443) is not blocked by a firewall or corporate proxy
  • If behind a proxy, set NODE_EXTRA_CA_CERTS or use the baseUrl constructor option to point to the correct endpoint

Client used after close()​

Calling await client.close() revokes tokens and releases the client. Any API call made afterwards will fail.

Fix: Create a new CandescentClient instance if you need to make further calls after closing.

Unexpected undefined fields in responses​

Optional fields in the OpenAPI spec are omitted from responses when not present — the SDK reflects that exactly.

Fix: Use optional chaining when accessing response fields:

const count = accounts.accounts?.length ?? 0;

Check the API Reference to confirm which fields are always present vs optional.

Pagination returns no results on subsequent pages​

Cause: Passing a page offset beyond the total result count.

Fix: Use PageIterator which handles page advancement and termination automatically. If iterating manually, check totalElements or totalPages in the first response before advancing.

Still stuck?​