​
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

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