> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zopio.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for the Zopio CLI

# Troubleshooting

This page covers common issues you might encounter when using the Zopio CLI and provides solutions to resolve them.

### Installation Problems

<Alert type="warning">
  If you encounter permission errors during installation, you may need to use sudo (on Linux/macOS) or run your terminal as administrator (on Windows).
</Alert>

#### Error: EACCES: permission denied

```bash theme={"system"}
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:**

```bash theme={"system"}
# 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:**

```bash theme={"system"}
# 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

```bash theme={"system"}
Unknown command: zopio some-command
```

**Solution:**

```bash theme={"system"}
# Check available commands
zopio --help

# Update to the latest version
npm update -g zopio-cli
```

#### Error: Missing required argument

```bash theme={"system"}
error: required option '-m, --model <model>' not specified
```

**Solution:**

```bash theme={"system"}
# 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

```bash theme={"system"}
Error: Project directory already exists and is not empty
```

**Solution:**

```bash theme={"system"}
# 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

```bash theme={"system"}
Error: Failed to download template: network error
```

**Solution:**

```bash theme={"system"}
# 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

```bash theme={"system"}
Error: Invalid field format. Expected format: name:type[:label]
```

**Solution:**

```bash theme={"system"}
# Use the correct field format
zopio crud -m User -f "name:string:Full Name,email:string:Email Address"
```

#### Error: Template not found

```bash theme={"system"}
Error: Template not found: component
```

**Solution:**

```bash theme={"system"}
# 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

```bash theme={"system"}
Error: Locale 'fr' already exists
```

**Solution:**

```bash theme={"system"}
# Check existing locales
cat i18nConfig.ts

# Update the locale instead of adding it
zopio i18n --update fr
```

#### Error: Missing translation files

```bash theme={"system"}
Error: Translation file not found: dictionaries/fr/common.json
```

**Solution:**

```bash theme={"system"}
# 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:

```bash theme={"system"}
# 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:

```bash theme={"system"}
# 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:

```bash theme={"system"}
# Remove configuration file
rm ~/.zopio/config.json

# Reinitialize configuration
zopio config --init
```

<Alert type="tip">
  If you encounter an issue not covered here, please report it on our GitHub repository: <a href="https://github.com/zopiolabs/cli/issues" target="_blank">[https://github.com/zopiolabs/cli/issues](https://github.com/zopiolabs/cli/issues)</a>
</Alert>