Fluent Commerce Logo
Docs

Troubleshooting the Fluent CLI (v2)

Essential knowledgeCore knowledge to understand Fluent Commerce

Intended Audience:

Technical User

Author:

Marco Heuer

Changed on:

30 Apr 2026

Overview

[Warning: empty required content area]

Key points

[Warning: empty required content area]
  • 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.

Common Issues and Solutions

Installation Issues

Issue: "Module already installed" Error
Symptoms:
`error: ! Failed to install module core: Module "fluent-commerce/core" version 2.2.1 is already installed. Aborting.
`
Cause: Module is already installed but being detected by actions log checkSolution 1: Let it skip (recommended)
`# Just re-run - it will automatically skip
fluent blueprint install accelerator.json -p myprofile -r RETAILER01
`
Solution 2: Force reinstall
`# Reinstall the module
fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --force`

Why it happens: - Module names might differ between blueprint and installed state - Example: Blueprint says `"core"` but installed as `"fluent-commerce/core"` - Smart resume catches this and skips automatically
Issue: Installation Stops Mid-Way
Symptoms:
`Module 5/10: inventory
error: Network timeout
error: ! Failed to install module inventory: Connection refused
`
Cause: Network interruption, API timeout, or module issueSolution: Resume from where it stopped
`# Just re-run the same command
fluent blueprint install accelerator.json -p myprofile -r RETAILER01
`
Result: - Modules 1-4: Automatically skipped - Module 5: Retried - Modules 6-10: InstalledVerification:
`# Check what got installed
fluent blueprint list -p myprofile
`
Issue: "Conflicts Detected" Error
Symptoms:
`error: Installation blocked due to conflicts:
error:   - legacy-order-module v1.0.0 (module): Incompatible with new architecture
`
Cause: Blueprint defines conflicts with currently installed modulesSolution 1: Remove conflicting module
`# Uninstall the conflicting module first
fluent module uninstall legacy-order-module -p myprofile -r RETAILER01

# Then retry blueprint installation
fluent blueprint install accelerator.json -p myprofile -r RETAILER01
`
Solution 2: Edit blueprint (if safe)
`# Remove conflict definition from blueprint JSON
# Only do this if you're certain there's no real conflict!
jq 'del(.conflicts[] | select(.name == "legacy-order-module"))' accelerator.json > accelerator-modified.json

# Install with modified blueprint
fluent blueprint install accelerator-modified.json -p myprofile -r RETAILER01
`
Solution 3: Force installation (dangerous)
`# This bypasses duplicate checks but NOT conflict checks
# Conflicts still block installation for safety
fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --force
`
Issue: Some Modules Skipped Unexpectedly
Symptoms:
`Summary:
 + Installed: 3
 - Skipped:   7
`
Cause: Modules are already installed from previous run or manual installationDiagnosis:
`# Check what's currently installed
fluent blueprint list -p myprofile

# Check module actions log
fluent module list -p myprofile -r RETAILER01
`
Solution 1: Accept skips (if modules are current versions) - If modules are already installed with correct versions, this is expected behaviour - No action neededSolution 2: Force reinstall (if versions need updating)
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --force
`

Issue: Module Downgrade Blocked

Symptoms:
`Module 1/5: order
⊝ Module order v1.1.0 is newer than blueprint version v1.0.0 - skipping downgrade
 (Use --force to downgrade)
`
Cause: Blueprint specifies an older version than currently installed, and `--force` flag not usedUnderstanding Smart Version Comparison: - Upgrade (v1.0.0 → v1.1.0): Installs automatically (no --force needed) - Same version (v1.0.0 → v1.0.0): Skips (use --force to reinstall) - Downgrade (v1.1.0 → v1.0.0): Blocked (requires --force for safety)Solution 1: Accept the skip (recommended)
`# Current version is newer, so skip is intentional
# No action needed if you want to keep the newer version
`
Solution 2: Force downgrade (if intentional rollback)
`# Explicitly allow downgrade with --force
fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --force
`
Output with --force:
`Module 1/5: order
- Downgrading module order: v1.1.0 → v1.0.0 (--force)
+ Module order installed successfully
`
Why downgrades are blocked by default: - Prevents accidental version rollbacks - Protects against using outdated blueprints - Ensures explicit confirmation for downgradesWhen to use --force for downgrade: - Rolling back to previous stable version - Testing with older version - Intentionally using older blueprint

Issue: Modules Not Upgrading Automatically

Symptoms:
`# Blueprint has newer versions but modules being skipped
Module 1/3: order
- Module order v1.0.0 is already installed - skipping
`
Expected Behaviour (Smart Version Comparison):
`Module 1/3: order
+ Upgrading module order: v1.0.0 → v1.1.0
+ Module order installed successfully
`
Diagnosis:Check 1: Blueprint has newer versions?
`# Check blueprint contents
fluent blueprint describe accelerator.json

# Check currently installed versions
fluent blueprint list -p myprofile
`
Check 2: Module versions are valid semver?
`# Invalid: "1.0.0-SNAPSHOT" might not compare correctly
# Valid: "1.0.0", "1.1.0", "2.0.0"
`
Solution 1: Verify blueprint versions
`{
 "modules": [
   {
     "name": "order",
     "version": "1.1.0"  // ← Make sure this is newer than installed
   }
 ]
}
`
Solution 2: Check installed module name format
`# Module names must match exactly
# Blueprint: "order" should match installed: "fluent-commerce/order"
# Blueprint: "acme/custom" should match installed: "acme/custom"
`
Solution 3: Force reinstall if version comparison fails
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --force
`

Issue: Selective Installation Filter Not Working

Symptoms:
`# Trying to install only "core" module but getting error
fluent blueprint install accelerator.json --include "core" -p myprofile -r RETAILER01
# Error: No modules matched include filter: core
`
Cause 1: Module name mismatchCheck module names in blueprint:
`fluent blueprint describe accelerator.json
# Look for exact module names in the "Modules" table
`
Solution:
`# Use exact name from blueprint
# If blueprint lists "fluent-commerce/core", use that:
fluent blueprint install accelerator.json --include "fluent-commerce/core" -p myprofile -r RETAILER01

# Or if blueprint lists just "core", use that:
fluent blueprint install accelerator.json --include "core" -p myprofile -r RETAILER01
`
Cause 2: Using both --include and --excludeError:
`error: Cannot use --include and --exclude together. Use one or the other.
`
Solution: Use only one filter:
`# Either include specific modules
fluent blueprint install accelerator.json --include "core,order" -p myprofile -r RETAILER01

# OR exclude specific modules
fluent blueprint install accelerator.json --exclude "test-module" -p myprofile -r RETAILER01
`
Cause 3: Typo in module namesWarning example:
`Warning: Module names not found in blueprint: cod, ordr
Filtered to 1 modules (from 5 total): inventory
`
Solution: Double-check spelling:
`# Correct spelling
fluent blueprint install accelerator.json --include "core,order,inventory" -p myprofile -r RETAILER01
`
Verification:
`# Describe blueprint to see all module names
fluent blueprint describe accelerator.json

# Should see:
# Modules (5)
#
# name                    version
# ----------------------  ---------
# core                    1.0.0
# order                   1.1.0
# inventory               1.0.0
`

Issue: Module Download Fails

Symptoms:
`error: Failed to prepare module: acme/custom-order-module
error: Module not found in repository
`
Possible Causes: 1. Module doesn't exist 2. Wrong module name 3. Invalid version 4. Network issues 5. Repository unavailableSolution 1: Verify module exists
`# Check module name and version in blueprint
fluent blueprint describe accelerator.json
`
Solution 2: Check network connectivity
`# Test API connectivity
curl -I https://api.fluentcommerce.com

# Test DNS resolution
nslookup api.fluentcommerce.com
`
Solution 3: Use local module path
`{
 "modules": [
   {
     "name": "acme/custom-order-module",
     "version": "2.5.2",
     "modulePath": "/path/to/local/acme-custom-order-module-2.5.2.zip"
   }
 ]
}
`
Solution 4: Try different base directory
`# Use writable directory with more space
fluent blueprint install accelerator.json \
 -p myprofile -r RETAILER01 \
 --base-dir /var/tmp/modules
`

Configuration Issues

Issue: Config Generation Fails

Symptoms:
`error: Failed to prepare module: Permission denied
error: EACCES: permission denied, open 'module.config.RETAILER01.base-module.json'
`
Possible Causes: 1. No write permission in current directory 2. Disk full 3. File locked by another processSolution 1: Check permissions
`# Check current directory permissions
ls -la

# Change to writable directory
cd ~/fluent-configs
fluent blueprint config accelerator.json -p myprofile -r RETAILER01
`
Solution 2: Check disk space
`# Check available space
df -h .

# Clean up space if needed
# Then retry
`
Solution 3: Close conflicting programs - Close any text editors that have config files open - Check for processes locking files: `lsof | grep module.config`

Issue: Config Files Not Found During Install

Symptoms:
`warn: Config file not found: module.config.RETAILER01.custom-order-module.json
info: Using auto-generated config
`
Cause: Expected config file doesn't exist or wrong namingSolution 1: Generate configs first
`# Generate all config files
fluent blueprint config accelerator.json -p myprofile -r RETAILER01

# Then install
fluent blueprint install accelerator.json -p myprofile -r RETAILER01
`
Solution 2: Check file naming Config files must match pattern:
`module.config.<RETAILER-REF>.<MODULE-SHORT-NAME>.json
`
Example:
`# Wrong names (won't be found):
config-custom-order-module.json
module.config.custom-order-module.json  # Missing retailer

# Correct name:
module.config.RETAILER01.custom-order-module.json
`
Solution 3: Verify retailer ref
`# Check profile's retailer ref
fluent profile list

# Ensure it matches config filename
`

Authentication Issues

Issue: "Authentication Failed"

Symptoms:
`error: Authentication failed for account
error: Invalid credentials
`
Solution 1: Verify profile
`# List profiles
fluent profile list

# Check current active profile
fluent profile active
`
Solution 2: Update credentials
`# Update profile with fresh credentials
fluent profile update myprofile
`
Solution 3: Check profile completeness
`# Profile must have account AND retailer for blueprint commands
fluent profile retailers myprofile
`

Issue: "Retailer Configuration Required"

Symptoms:
`error: Retailer configuration required
`
Cause: Profile doesn't have retailer setSolution 1: Set retailer in command
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01
`
Solution 2: Set active retailer
`# Set as active retailer in profile
fluent profile use myprofile RETAILER01

# Then command doesn't need -r flag
fluent blueprint install accelerator.json -p myprofile
`
Solution 3: Add retailer to profile
`# List available retailers
fluent profile retailers myprofile

# Use one from the list
fluent profile use myprofile <retailer-ref>
`

Blueprint File Issues

Issue: "Blueprint File Not Found"

Symptoms:
`error: Blueprint file not found: accelerator.json
`
Solution 1: Check file path
`# List files in current directory
ls -la *.json

# Use absolute path
fluent blueprint describe /full/path/to/accelerator.json
`
Solution 2: Check file extension
`# Blueprint must be .json
# If you have .yaml, convert to JSON:
# (manual conversion needed)
`

Issue: "Blueprint Validation Failed"

Symptoms:
`error: Blueprint validation failed:
error:   [INVALID_VERSION] Module version "abc" is not valid semver
error:   Field: modules[2].version
`
Cause: Blueprint has invalid structure or valuesSolution 1: Check JSON syntax
`# Validate JSON
cat accelerator.json | jq .

# If jq shows error, fix JSON syntax
`
Solution 2: Validate semver versions
`{
 "modules": [
   // Invalid versions:
   { "version": "abc" },       // Not semver
   { "version": "v1.0.0" },    // Don't use 'v' prefix
   { "version": "1.0" },       // Missing patch version
   { "version": "^1.0.0" },    // Ranges not allowed for modules
   { "version": "~1.0.0" },    // Ranges not allowed for modules
   { "version": ">=1.0.0" },   // Ranges not allowed for modules

   // Valid versions:
   { "version": "1.0.0" },     // Exact version
   { "version": "latest" }     // Latest keyword
 ]
}
`
Important: Module versions must be exact. Ranges like `^1.0.0` are only allowed in conflict definitions, not module versions.Solution 3: Check required fields
`{
 // Required fields:
 "name": "my-blueprint",
 "version": "1.0.0",
 "description": "Description here",
 "created": "2024-01-01T00:00:00Z",
 "modules": [
   {
     "name": "module-name",  // Required
     "version": "1.0.0"      // Required
   }
 ]
}
`

Issue: Invalid Module Path

Symptoms:
`error: Module file not found: ./modules/my-module.zip
`
Cause: modulePath in blueprint points to non-existent fileSolution 1: Verify file exists
`# Check if file exists
ls -la ./modules/my-module.zip

# Use absolute path
pwd  # Get current directory
# Update blueprint with full path
`
Solution 2: Use correct path format
`{
 "modules": [
   {
     "name": "my-module",
     "version": "1.0.0",
     // Different path formats:
     "modulePath": "/absolute/path/to/module.zip",
     "modulePath": "./relative/path/to/module.zip",
     "modulePath": "./modules/",  // Directory - filename auto-constructed
     "modulePath": "https://example.com/module.zip"  // URL
   }
 ]
}
`

Performance Issues

Issue: Installation Very Slow

Symptoms: - Installation takes much longer than expected - Long pauses between modulesPossible Causes: 1. Large module downloads 2. Network latency 3. API throttling 4. Wait time between tasksSolution 1: Reduce wait time
`# Default wait is 1000ms (1 second)
# Reduce to 100ms if API allows
fluent blueprint install accelerator.json \
 -p myprofile -r RETAILER01 \
 --wait 100
`
Solution 2: Use local modules
`{
 "modules": [
   {
     "name": "my-module",
     "version": "1.0.0",
     "modulePath": "/local/cache/my-module-1.0.0.zip"
   }
 ]
}
`
Solution 3: Check network
`# Test download speed
curl -o /dev/null https://api.fluentcommerce.com/test-file

# Check latency
ping api.fluentcommerce.com
`

Issue: Disk Space Full

Symptoms:
`error: ENOSPC: no space left on device
`
Cause: Temporary directory filled with extracted modulesSolution 1: Clean temp directory
`# Check temp directory size
du -sh /tmp/fluent-*

# Clean old extractions
rm -rf /tmp/fluent-module-*

# Retry
fluent blueprint install accelerator.json -p myprofile -r RETAILER01
`
Solution 2: Use different base directory
`# Use directory on drive with more space
fluent blueprint install accelerator.json \
 -p myprofile -r RETAILER01 \
 --base-dir /var/tmp
`
Solution 3: Clean up between modules The CLI automatically cleans up after each module, but manual cleanup can help:
`# Monitor during installation
watch -n 5 'df -h /tmp'
`

Dry Run Issues

Issue: Dry Run Passes But Install Fails

Symptoms:
`# Dry run succeeds
fluent blueprint install accelerator.json --dry-run
# No conflicts detected

# Real install fails
fluent blueprint install accelerator.json
# Module installation failed
`
Cause: Dry run only validates structure and conflicts, not actual module installationWhat Dry Run Checks: - Blueprint validation - Authentication - Conflict detection - NOT checked: Module download/extraction - NOT checked: Module installation - NOT checked: Configuration validitySolution: Dry run is for pre-flight validation only. Module installation issues only surface during real installation.

Check Installation State
`# What blueprints are installed?
fluent blueprint list -p myprofile

# What modules are installed?
fluent module list -p myprofile -r RETAILER01

# What's in the blueprint?
fluent blueprint describe accelerator.json
`

Verify Authentication
`# Check profiles
fluent profile list

# Check active profile
fluent profile active

# Check retailers for profile
fluent profile retailers myprofile
`

Test Connectivity
`# Test API connectivity
curl -I https://api.fluentcommerce.com

# Check DNS
nslookup api.fluentcommerce.com

# Test auth
fluent settings list -p myprofile -r RETAILER01 -n "fc.system.version"
`

Debug Mode
`# Enable debug logging (if CLI supports)
export DEBUG=fluent:*
fluent blueprint install accelerator.json -p myprofile -r RETAILER01

# Or increase verbosity
fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --verbose
`

Before Installation

  • Validate blueprint structure` fluent blueprint validate accelerator.json
    `
  • Preview blueprint contents` fluent blueprint describe accelerator.json
    `
  • Validate with dry run` fluent blueprint install accelerator.json --dry-run
    `
  • Check current state` fluent blueprint list
    fluent module list
    `
  • Generate configs first` fluent blueprint config accelerator.json
    # Review and edit configs
    `
  • Test in non-production` fluent blueprint install accelerator.json -p dev -r DEV01
    `

During Installation

  • Don't interrupt unless absolutely necessary
  • Monitor output for warnings
  • Keep terminal open and visible
  • Note any errors for troubleshooting

After Installation

  • Verify installation` fluent blueprint list
    `
  • Check summary statistics` Summary:
     + Installed: 10  ← Should match expected
     - Skipped:   0   ← Understand why any skipped
    `
  • Test functionality - Verify modules work as expected
  • Document results - Keep logs for audit trail

Log Collection

When reporting issues, include:
  • Command executed` fluent blueprint install accelerator.json -p myprofile -r RETAILER01
    `
  • Complete output (sanitise sensitive data)
  • Blueprint file (sanitise if needed)` fluent blueprint describe accelerator.json
    `
  • Environment info` fluent --version
    node --version
    fluent profile list
    `

Common Support Questions

Q: Can I pause and resume installation later? A: Yes! Just re-run the same command. Already-installed modules will be skipped automatically.Q: How do I reinstall specific modules? A: Use `--force` flag to reinstall all modules, or manually uninstall specific modules first.Q: Why are modules getting skipped? A: They're already installed. Use `blueprint list` and `module list` to verify. Use `--force` to reinstall.Q: Can I change module order? A: Yes, edit the blueprint JSON `modules` array. Put dependencies first.Q: How do I check if installation was successful? A: Check the summary statistics and run `blueprint list` to verify.