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 automaticallyIssue: 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 blueprintIssue: 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
`
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
`
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"
`
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
`
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.- Blueprint Overview - Understanding blueprints
- Blueprint Validate Command - Validate blueprint structure and business rules
- Blueprint Install Command - Detailed install documentation
- Blueprint List Command - Checking installed blueprints
- Blueprint Config Command - Generating configurations
