Fluent Commerce Logo
Docs

CLI Blueprint Troubleshooting Guide

How-to GuideStep-by-step guides to achieve a specific scenario or setup.

Author:

Marco Heuer

Changed on:

30 Apr 2026

Key Points

  • Smart Resume for Recovery: If an installation fails due to network or timeout issues, simply re-running the same command allows the CLI to skip successful modules and resume from the point of failure.
  • Version Safety Rails: The system automatically upgrades modules to newer versions but blocks downgrades and re-installs of the same version to prevent accidental data loss unless the `--force` flag is used.
  • Conflict & Validation Gates: Installations are blocked if blueprint-defined conflicts with existing modules are detected. Use `blueprint describe` to identify exact module names if filters or conflict rules trigger errors.
  • Strict Config Naming: Custom configurations are only recognized during install if they follow the `module.config.<RETAILER-REF>.<MODULE-SHORT-NAME>.json` pattern; otherwise, the system defaults to auto-generated configs.

Steps

Installation Issues

Configuration Issues

Authentication Issues

Blueprint File Issues

Performance Issues

Dry Run Issues

Diagnostic Commands

Best Practices to Avoid Issues

Getting Help