Querying, References & Content Retrieval

Developers are unable to distinguish between "Draft" (unpublished) and "Published" entries when using the Management SDK for auditing or migration.

Root Cause

The Management SDK (CMA) returns all entries by default regardless of status; the publish_details metadata must be explicitly requested and inspected to verify live status.

Resolution

1. Fetch entries using CMA with include_publish_details: true.
2. Inspect publish_details in the response.
3. Treat empty publish_details (or version mismatch logic in your workflow) as unpublished/draft-like state.

Example:

const entry = await client
  .stack({ api_key: process.env.CS_API_KEY })
  .contentType('blog')
  .entry('entry_uid')
  .fetch({ include_publish_details: true });

The programmatic output correctly identifies which entries are live and which are drafts. Escalate if publish_details are missing for entries known to be published. Provide Entry UID.

The SDK returns a 422 Unprocessable Entity error when query methods (like filters or includes) use unsupported or misspelled parameters.

Root Cause

The query uses misspelled parameters, unsupported filter methods for a specific field type, or hidden characters that violate API validation rules.

Resolution

1. Check the SDK method syntax; ensure you are using the correct helper methods (e.g., .includeCount() vs manually adding parameters).
2. Verify that parameters like include_fallback are supported for the specific content type.
3. Ensure no trailing spaces or hidden characters exist in the parameter strings.

The query executes successfully and returns the expected count or localized content. Escalate if the same query works via cURL but fails via SDK. Provide the generated request URL.

Published entries can still return 404 when the environment/locale/region does not match the publish target.

Root Cause

The request is targeting a different environment or locale than the one where the entry was successfully published.

Resolution

1. Confirm entry is published to the same environment used by SDK config.
2. Ensure locale code matches exactly.
3. Verify region/host alignment for the stack.

Entry fetch returns 200 and expected UID for requested environment/locale. Escalate with entry UID, environment, locale, and region used in request.

Reference fields may return empty arrays/UID-only data when references are not explicitly expanded or not publish-aligned.

Root Cause

Reference fields are not explicitly expanded using .includeReference(), or the referenced entries have not been published to the target environment.

Resolution

1. Use includeReference(...) for required reference fields.
2. For nested refs, include dotted paths as needed.
3. Verify referenced entries are published to the same environment/locale as the parent entry.

Response returns populated referenced objects (not empty arrays for valid linked data). Escalate with parent entry UID, reference field UID/path, and publish targets.

Developers cannot programmatically access "Last Modified By" or "Owner" details via the SDK, as these are excluded from default responses for performance.

Root Cause

Metadata fields like "Owner" or "Last Modified By" are excluded from standard entry responses to optimize performance and must be requested via specific inclusion parameters.

Resolution

1. Use CMA (not Delivery SDK) for metadata workflows.
2. Fetch entry-level metadata through documented entry params:
   • entry(uid).fetch({ include_workflow: true, include_publish_details: true })
3. Fetch action/user audit trail through stack audit-log APIs:
   • stack.auditLog().fetchAll({ include_count: true, limit, skip })
   • stack.auditLog('log_uid').fetch()
4. Verify the token has read access for the stack objects being queried.

const entry = await client
  .stack({ api_key: process.env.CS_API_KEY })
  .contentType('blog')
  .entry('entry_uid')
  .fetch({ include_workflow: true, include_publish_details: true });

const logs = await client
  .stack({ api_key: process.env.CS_API_KEY })
  .auditLog()
  .fetchAll({ include_count: true, limit: 10, skip: 0 });

Entry fetch returns metadata fields (including workflow/publish context), and audit-log calls return actor/action records for the stack. Escalate with entry UID, audit-log request params, token type, and sample response payload if metadata is still missing.

The SDK returns content in the master language even when a different locale is requested, or it returns a 404 if the locale is not properly specified.

Root Cause

The query does not explicitly define the .locale() parameter, or the requested locale code does not match the exact casing/format defined in the stack.

Resolution

1. Use .locale('locale-code') on Delivery SDK queries/entry fetches.
2. Confirm the target locale is enabled and published for the entry.
3. Use exact locale code casing/format as defined in stack locales.

const localizedEntry = await stack
  .contentType('article')
  .entry('entry_uid')
  .locale('fr-fr')
  .fetch();

Returned fields contain localized values (or expected fallback behavior if locale content is unavailable). Escalate with entry UID, locale code, and publish evidence when locale data is still missing.

Data contained within a Global Field is missing from the final SDK response, even though other entry fields are present.

Root Cause

The field is restricted by role-based permissions, or the global field schema was updated without re-publishing the affected entries.

Resolution

Global field payload may appear missing due to model visibility, permission, or publish-state mismatch.

1. Verify the global field is not hidden/restricted in the content model.
2. Confirm token roles can access the field data.
3. Re-publish content type/entries if model updates were recent.

Entry response includes expected global field object for the published target. Escalate with content type UID, field UID, and role/token details.