CLI Blueprint Troubleshooting Guide
How-to Guide
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.
Prerequisites
Steps
Installation Issues
Issue: "Module already installed" Error
Symptoms:
Cause: Module is already installed but being detected by actions log checkSolution 1: Let it skip (recommended)
Solution 2: Force reinstall
Why it happens: - Module names might differ between blueprint and installed state - Example: Blueprint says
`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 RETAILER01Solution 2: Force reinstall
`# Reinstall the module
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --forceWhy 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:
error: Network timeout
error: ! Failed to install module inventory: Connection refused
Cause: Network interruption, API timeout, or module issueSolution: Resume from where it stopped
Result: - Modules 1-4: Automatically skipped - Module 5: Retried - Modules 6-10: InstalledVerification:
`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 RETAILER01Result: - Modules 1-4: Automatically skipped - Module 5: Retried - Modules 6-10: InstalledVerification:
`# Check what got installed
`fluent blueprint list -p myprofileIssue: 'Conflicts Detected' Error
Symptoms:
error: - legacy-order-module v1.0.0 (module): Incompatible with new architecture
Cause: Blueprint defines conflicts with currently installed modulesSolution 1: Remove conflicting module
Solution 2: Edit blueprint (if safe)
Solution 3: Force installation (dangerous)
`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 RETAILER01Solution 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 RETAILER01Solution 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 --forceIssue: Some Modules Skipped Unexpectedly
Symptoms:
+ Installed: 3
- Skipped: 7
Cause: Modules are already installed from previous run or manual installationDiagnosis:
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)
`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 RETAILER01Solution 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 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
Output with --force:
- 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
`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 --forceOutput 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 myprofileCheck 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 RETAILER01Cause 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 RETAILER01Cause 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 RETAILER01Verification:
`# 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: 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
Solution 2: Check network connectivity
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
-p myprofile -r RETAILER01 \
--base-dir /var/tmp/modules
`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.jsonSolution 2: Check network connectivity
`# Test API connectivity
`curl -I https://api.fluentcommerce.com`# Test DNS resolution
`nslookup api.fluentcommerce.comSolution 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: 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
fluent blueprint config accelerator.json -p myprofile -r RETAILER01
Solution 2: Check disk space
`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-configsfluent 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:
info: Using auto-generated config
Cause: Expected config file doesn't exist or wrong namingSolution 1: Generate configs first
Solution 2: Check file naming Config files must match pattern:
Example:
module.config.custom-order-module.json
Solution 3: Verify retailer ref
`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 RETAILER01Solution 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.jsonmodule.config.custom-order-module.json
`# Missing retailer
``# Correct name:
`module.config.RETAILER01.custom-order-module.jsonSolution 3: Verify retailer ref
`# Check profile's retailer ref
`fluent profile list`# Ensure it matches config filename`Authentication Issues
Issue: "Authentication Failed"
Symptoms:
error: Invalid credentials
Solution 1: Verify profile
Solution 2: Update credentials
Solution 3: Check profile completeness
`error: Authentication failed for account`error: Invalid credentials
Solution 1: Verify profile
`# List profiles
`fluent profile list`# Check current active profile
`fluent profile activeSolution 2: Update credentials
`# Update profile with fresh credentials
`fluent profile update myprofileSolution 3: Check profile completeness
`# Profile must have account AND retailer for blueprint commands
`fluent profile retailers myprofileIssue: "Retailer Configuration Required"
Symptoms:
Cause: Profile doesn't have retailer setSolution 1: Set retailer in command
Solution 2: Set active retailer
Solution 3: Add retailer to profile
`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 myprofileSolution 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:
Solution 1: Check file path
Solution 2: Check file extension
`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.jsonSolution 2: Check file extension
`# Blueprint must be .json
# If you have .yaml, convert to JSON:
# (manual conversion needed)`Issue: "Blueprint Validation Failed"
Symptoms:
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
"modules": [
}
Important: Module versions must be exact. Ranges like
"version": "1.0.0",
"description": "Description here",
"created": "2024-01-01T00:00:00Z",
"modules": [
{
"name": "module-name",
]
}
`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:
Cause: modulePath in blueprint points to non-existent fileSolution 1: Verify file exists
"modules": [
{
"name": "my-module",
"version": "1.0.0",
"modulePath": "./relative/path/to/module.zip",
"modulePath": "./modules/",
]
}
`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
-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
`# 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.comIssue: Disk Space Full
Symptoms:
Cause: Temporary directory filled with extracted modulesSolution 1: Clean temp directory
Solution 2: Use different base directory
-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:
`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 RETAILER01Solution 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.Diagnostic Commands
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.jsonVerify Authentication
`# Check profiles
`fluent profile list`# Check active profile
`fluent profile active`# Check retailers for profile
`fluent profile retailers myprofileTest 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 --verboseBest Practices to Avoid Issues
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
Getting Help
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.
