@dscodotco/theme-cli/docs/troubleshooting.md

A CLI tool for developing Shopify themes

# Troubleshooting Guide

This guide helps you diagnose and fix common issues you might encounter while using Theme CLI.

## Common Issues

### Installation Issues

#### Error: EACCES: permission denied

**Problem**: Permission errors during global installation.

**Solution**:
```bash
# Option 1: Use sudo (not recommended)
sudo npm install -g @dscodotco/theme-cli

# Option 2: Fix npm permissions (recommended)
sudo chown -R $USER:$GROUP ~/.npm
sudo chown -R $USER:$GROUP ~/.config
```

#### Error: Unable to resolve dependency tree

**Problem**: Dependency conflicts with other packages.

**Solution**:
```bash
# Option 1: Force installation
npm install --force

# Option 2: Clear npm cache
npm cache clean --force
npm install
```

### Authentication Issues

#### Error: Invalid API credentials

**Problem**: Incorrect or missing Shopify API credentials.

**Solution**:
1. Verify your `.env` file contains:
   ```env
   SHOPIFY_STORE_NAME=your-store.myshopify.com
   SHOPIFY_API_KEY=your_api_key
   SHOPIFY_API_PASSWORD=your_api_password
   SHOPIFY_THEME_ID=123456789
   ```
2. Check API key permissions in Shopify admin
3. Ensure the store name includes `.myshopify.com`

#### Error: Theme access denied

**Problem**: Insufficient permissions for theme operations.

**Solution**:
1. Verify API scopes include:
   - `read_themes`
   - `write_themes`
2. Check theme ID exists and is accessible
3. Ensure store has development store status

### Development Server Issues

#### Error: Port 3000 is already in use

**Problem**: Port conflict with another service.

**Solution**:
```bash
# Option 1: Kill process using port 3000
lsof -i :3000
kill -9 <PID>

# Option 2: Use different port
theme-cli dev --port 3001
```

#### Error: WebSocket connection failed

**Problem**: Hot reload not working.

**Solution**:
1. Check firewall settings
2. Verify WebSocket port is not blocked
3. Try disabling antivirus temporarily
4. Use HTTPS for secure WebSocket connection:
   ```bash
   theme-cli dev --https
   ```

### Theme Deployment Issues

#### Error: Theme upload failed

**Problem**: Unable to upload theme files.

**Solution**:
1. Check internet connection
2. Verify file permissions
3. Check theme file size limits
4. Try deploying specific files:
   ```bash
   theme-cli deploy --files "templates/*"
   ```

#### Error: Asset compilation failed

**Problem**: Issues with asset pipeline.

**Solution**:
1. Check asset syntax
2. Verify dependencies are installed
3. Clear cache and rebuild:
   ```bash
   theme-cli clean
   theme-cli build
   ```

### Template Rendering Issues

#### Error: Template not found

**Problem**: Unable to locate template files.

**Solution**:
1. Verify template exists in correct directory
2. Check file naming convention
3. Clear template cache:
   ```bash
   theme-cli clean --templates
   ```

#### Error: Liquid syntax error

**Problem**: Invalid Liquid template syntax.

**Solution**:
1. Validate Liquid syntax
2. Check for missing end tags
3. Use Theme Check linter:
   ```bash
   theme-cli lint
   ```

## Debugging Tools

### Log Files

Access detailed logs for troubleshooting:

```bash
# View development server logs
theme-cli dev --verbose

# View deployment logs
theme-cli deploy --verbose

# Export logs to file
theme-cli dev --verbose > theme-cli.log 2>&1
```

### Network Debugging

Monitor network requests:

```bash
# Enable request logging
theme-cli dev --log-level debug

# Monitor specific requests
theme-cli dev --log-filter "api/*"
```

### Performance Analysis

Identify performance bottlenecks:

```bash
# Run performance audit
theme-cli audit

# Profile asset compilation
theme-cli build --profile
```

## Error Messages

### Common Error Codes

| Code | Description | Solution |
|------|-------------|----------|
| E001 | Invalid credentials | Check API credentials |
| E002 | Theme not found | Verify theme ID |
| E003 | Permission denied | Check API scopes |
| E004 | Network error | Check connectivity |
| E005 | Compilation error | Check asset syntax |

### Error Reporting

Submit detailed bug reports:

1. Enable debug mode:
   ```bash
   theme-cli --debug
   ```

2. Reproduce the issue

3. Collect logs:
   ```bash
   theme-cli logs export
   ```

4. Submit issue with:
   - Error message
   - Steps to reproduce
   - Log files
   - Theme CLI version
   - Node.js version

## Prevention

### Best Practices

1. **Version Control**
   - Use Git
   - Commit frequently
   - Back up before deployments

2. **Development Workflow**
   - Use development themes
   - Test in staging environment
   - Follow deployment checklist

3. **Maintenance**
   - Keep dependencies updated
   - Monitor API changes
   - Review security updates

### Monitoring

Set up monitoring for:

1. **Server Health**
   - CPU usage
   - Memory usage
   - Response times

2. **API Usage**
   - Rate limits
   - Error rates
   - Response times

3. **Asset Performance**
   - Compilation times
   - Bundle sizes
   - Cache hit rates

## Getting Help

### Community Resources

- [GitHub Issues](https://github.com/dsco/theme-cli/issues)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/shopify-theme-cli)
- [Community Discord](https://discord.gg/dsco)

### Support Channels

1. **Documentation**
   - [API Reference](./api/README.md)
   - [Tutorials](./tutorials/README.md)
   - [Examples](./examples/README.md)

2. **Professional Support**
   - [Shopify Partners](https://partners.shopify.com)
   - [Theme CLI Support](https://support.dsco.dev)
   - [Custom Development](https://dsco.dev/services)

### Updates

Stay informed about:

1. **Version Updates**
   - Release notes
   - Breaking changes
   - Security patches

2. **API Changes**
   - Deprecation notices
   - New features
   - Best practices

3. **Community News**
   - Blog posts
   - Tutorials
   - Case studies