Customer Knowledge Base
Customer Knowledge Base
Breadcrumbs

HCMS: Missing Image Service Configuration Prevents Schema Deployment

1. Overview

This KB explains how to diagnose and resolve cases where an HCMS schema cannot be deployed because the image service or related storage configuration is incomplete or missing.
It applies when schema import/export fails with errors indicating missing image, file system, or output‑channel‑related configuration.

2. Symptoms

  • Schema deployment fails with an error indicating that image service configuration is missing.

  • API calls to assets return 404 responses even though schema import appears successful in other environments.

  • Multiple HCMS API configurations exist unexpectedly, each serving different output channels.

  • HCMS appears partially installed or configuration differs between environments.

3. Common Causes

  • Missing or incomplete image service configuration in HeadlessCms.xml or DataStore.xml.

  • Inconsistent configuration across environments.

  • Multiple API configurations/output channels created without a defined architecture.

  • Installation or setup tasks not fully completed.

4. Diagnostics

4.1 Customer/Partner

  • Check that a clear definition of required output channels, API clients, and storage buckets exists before configuration.

  • Confirm whether one or multiple API endpoints are intended for the project.

  • Validate that all required installation information has been provided (storage bucket names, regions, expected image mappings, etc.).

  • Test the /schema/<name> endpoint to confirm whether a compilation error is returned.

  • Verify whether the schema deploys correctly in at least one fully configured environment

4.2 Infra/DevOps

  • Confirm that HeadlessCms.xml contains a complete image service configuration, including:

    • image storage definitions

    • S3 or file‑system mappings

    • output‑channel settings

    • image cache settings (where required)

  • Validate that DataStore.xml includes the required file storage entries for the environment.

  • Ensure that all required storage resources exist and match the configuration.

  • Reproduce the schema deployment to confirm whether HTTP 400 is returned. 

4.3 censhare Support

  • Verify whether HCMS installation tasks were completed according to the standard installation checklist.

  • Compare configuration across environments to identify missing sections.

  • Reproduce schema deployment to confirm the same compilation error.

  • Validate that only the intended API clients and output channels are active.

  • Confirm that compilation errors from /schema/<name> are resolved after configuration fixes.

5. Mitigation

  • Add or correct the image service configuration in HeadlessCms.xml and DataStore.xml according to project requirements.

  • Remove duplicate or unintended HCMS API configurations if only one is required.

  • Re-run the schema deployment after the configuration changes.

  • Ensure the configuration matches the architecture defined for the environment (storage, buckets, regions, output channels).

  • Re-test asset retrieval via the API once schema import succeeds.

6. Best Practices

  • Define all required HCMS components (output channels, storage buckets, API clients) before installation.

  • Maintain consistent configuration across environments to avoid deployment discrepancies.

  • Use a dedicated implementation or project ticketing system for configuration tasks; avoid standard support tickets for installation-driven processes.

7. When to Contact Support

  • Schema deployment continues to fail even after confirming that image service and file storage configurations are correct.

  • API endpoints return unexpected 404s after successful schema import.

  • Multiple API configurations exist and it is unclear which should be retained.

  • Environment comparison indicates missing components but the correct configuration is not known

8. Information Required

  • Expected number of API clients and output channels.

  • Intended storage configuration (S3 or file system), including required paths or buckets.

  • Complete environment-specific HCMS configuration files (sanitized if needed).

  • Exact error message from schema deployment.

  • Confirmation whether other environments function correctly.