Troubleshooting
This page covers common issues you might encounter when using the Zopio CLI and provides solutions to resolve them.
Installation Problems
Error: EACCES: permission denied
npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied
Solution:
# On Linux/macOS
sudo npm install -g zopio-cli
# Or install locally
npm install --save-dev zopio-cli
Error: Cannot find module ‘zopio-cli’
Solution:
# Make sure the package is installed
npm list -g zopio-cli
# If not found, reinstall
npm install -g zopio-cli
# Check your PATH environment variable
echo $PATH
Command Execution Issues
Error: Unknown command
Unknown command: zopio some-command
Solution:
# Check available commands
zopio --help
# Update to the latest version
npm update -g zopio-cli
Error: Missing required argument
error: required option '-m, --model <model>' not specified
Solution:
# Check command syntax
zopio crud-unified --help
# Provide the required arguments
zopio crud-unified -m User -f "name:string,email:string"
Project Initialization Issues
Error: Directory already exists
Error: Project directory already exists and is not empty
Solution:
# Initialize in a new directory
mkdir my-new-project
cd my-new-project
zopio init
# Or force initialization (use with caution)
zopio init --force
Error: Failed to download template
Error: Failed to download template: network error
Solution:
# Check your internet connection
# Try using a different template
zopio init --template minimal
# Or use a local template
zopio init --template-path ./my-template
Code Generation Issues
Error: Invalid field format. Expected format: name:type[:label]
Solution:
# Use the correct field format
zopio crud -m User -f "name:string:Full Name,email:string:Email Address"
Error: Template not found
Error: Template not found: component
Solution:
# Check available templates
ls .zopio/templates
# Create the missing template
mkdir -p .zopio/templates/component
touch .zopio/templates/component/index.ts.hbs
Internationalization Issues
Error: Locale already exists
Error: Locale 'fr' already exists
Solution:
# Check existing locales
cat i18nConfig.ts
# Update the locale instead of adding it
zopio i18n --update fr
Error: Missing translation files
Error: Translation file not found: dictionaries/fr/common.json
Solution:
# Create the missing directory structure
mkdir -p dictionaries/fr
# Create the missing file
echo '{}' > dictionaries/fr/common.json
# Synchronize translations
zopio i18n --sync
Debugging
You can enable debug mode to get more detailed logs:
# Set log level to debug
ZOPIO_LOG_LEVEL=debug zopio command
# Or use the debug flag
zopio command --debug
Logs
The CLI logs are stored in the following locations:
- Windows:
%USERPROFILE%\.zopio\logs
- macOS/Linux:
~/.zopio/logs
You can view the logs to diagnose issues:
# View the latest log
cat ~/.zopio/logs/zopio-cli.log
# View error logs
grep ERROR ~/.zopio/logs/zopio-cli.log
Configuration Reset
If you suspect your CLI configuration is corrupted, you can reset it:
# Remove configuration file
rm ~/.zopio/config.json
# Reinitialize configuration
zopio config --init
