Skip to main content

Troubleshooting

This guide provides solutions for common issues encountered while using Klarity ImageFactory. If you encounter an error not listed here, please contact Nordcloud support.

Account and Credential Issues​

ACCESS_ERROR​

This error indicates that ImageFactory cannot authenticate with your cloud provider account.

  • Cause: Incorrect credential format, expired secrets, or insufficient permissions in the target account.
  • Solution:
    1. Verify that the IAM role or service principal has the required trust policy allowing ImageFactory to assume it.
    2. Ensure all mandatory permissions for the provider are attached to the role.
    3. Check for any service control policies (SCPs) or conditional access policies that might be blocking access.
    4. Use the Recheck feature in the Cloud Credentials section of the Web UI to trigger a fresh validation.

ACCESS_MISSING​

The system cannot find the credentials required for the operation.

  • Cause: Credentials were not provided during account onboarding or were deleted.
  • Solution: Update the account record with the correct credentials or upload the required service principal key file.

Template and Build Issues​

TEMPLATE_ERROR​

The template configuration is invalid and cannot be processed.

  • Cause: The selected distribution is not available for the chosen provider, or the components are incompatible with the operating system.
  • Solution: Review the template configuration. Ensure the distribution ID is correct and that all selected components support the target OS family (e.g., don't use Windows-only components on a Linux distribution).

IMAGE_ERROR​

The build or test phase of the image creation process failed.

  • Cause: A component script returned a non-zero exit code, the build environment lacked necessary permissions, or the source image was unavailable.
  • Solution:
    1. Open the Image Details view and check the build logs for specific error messages.
    2. If a custom component failed, verify the script logic and ensure all required properties are correctly defined.
    3. Check if the target cloud account has reached its resource limits (e.g., VPC or instance limits).

IMAGE_QUEUED (Long Duration)​

The image remains in the queued state for an extended period.

  • Cause: The system is at maximum build capacity. ImageFactory has concurrent execution limits on image builds.
  • Solution: Builds are processed on a first-in, first-out (FIFO) basis. Please wait for existing builds to complete. If the issue persists for several hours, contact support.

Distribution and Lifecycle Issues​

Deprecated Distribution​

A distribution marked as deprecated can no longer be used for new templates.

  • Solution: Existing templates using this distribution will continue to work, but you should migrate to a newer distribution version as soon as possible to ensure continued support and security updates.

EOL (End of Life) Distribution​

The distribution has reached its official end-of-life date.

  • Solution: While ImageFactory may still allow builds, it is strongly recommended to migrate to a supported distribution. EOL distributions no longer receive security patches from the vendor.

Component Issues​

Invalid Ansible Playbook​

Ansible components fail during the build process.

  • Cause: The playbook YAML is malformed, or the hosts field is not set correctly.
  • Solution: Ensure the playbook is valid YAML. The hosts field must be set to default or all. The playbook must also pass the internal schema validation used by ImageFactory.

Cannot use Ansible for TEST stage​

An error occurs when trying to add an Ansible component to the test phase.

  • Cause: By design, test components must be implemented using SHELL or POWERSHELL. Ansible is only supported for the BUILD stage.
  • Solution: Convert your test logic into a shell script or PowerShell script.

Azure-Specific Issues​

Error in ImageFactory UI: Internal error. Please contact Nordcloud support. or Image was built successfully, but we were unable to distribute it.

Actual Error (found in Azure audit logs): Required parameter 'galleryImageVersionName' is missing (null)

  • Cause: This misleading error occurs when attempting to publish an image with different hardware features (such as NVMe Controller or Trusted Launch) to an existing Azure Compute Gallery image definition. Azure Compute Gallery image definitions are immutable regarding hardware features.
  • Common Scenario:
    • You created a template without NVMe Controller enabled
    • You deleted the template from ImageFactory
    • You created a new template with the same name but with NVMe Controller enabled
    • The old image definition still exists in your Azure Compute Gallery
    • Distribution fails with the "galleryImageVersionName" error in Azure audit logs
  • Solution:
    1. Change the Name field in the Compute gallery VM image definition section of your template to create a new image definition (e.g., change "Windows-Server-2025" to "Windows-Server-2025-NVMe")
    2. Or manually delete the existing image definition from your Azure Compute Gallery before rebuilding the template
  • Prevention: Always use unique names when changing hardware features like NVMe Controller or Trusted Launch. Deleting a template from ImageFactory does not delete the corresponding image definition from Azure Compute Gallery.
  • Debugging: Check your Azure Activity Log or audit logs to see the actual API error message from Azure.

Permission and API Issues​

401 Unauthorized​

  • Cause: Your authentication token has expired or the API key is invalid.
  • Solution: Re-authenticate through the Web UI or verify that your API key secret is correct and the key has not been deleted.

403 Forbidden​

  • Cause: Your user or API key lacks the necessary role permissions for the requested operation.
  • Solution: Check your Role Bindings. Ensure you have a role assigned that includes the required action and resource permissions for the target customer.

API Rate Limiting​

  • Cause: Too many requests were sent in a short period.
  • Solution: Implement exponential backoff in your scripts. Use pagination (page and limit parameters) when retrieving large lists of resources to reduce the load on the API.