# TROUBLESHOOTING.md

## TSYSDevStack - Toolboxes - DocsAndDiagrams

Troubleshooting Guide for the Document Production Workhorse Container

---

## 🐛 Common Issues and Solutions

### Docker Container Won't Start

**Issue**: Container fails to start with permission errors

**Solution**:
```bash
# Check if Docker daemon is running
sudo systemctl status docker

# If not running, start it
sudo systemctl start docker

# Ensure your user is in the docker group
sudo usermod -aG docker $USER
# Then log out and log back in
```

### Permission Denied Errors

**Issue**: Getting permission errors when accessing mounted volumes

**Solution**:
1. The container runs as user `tsysdevstack` with UID 1000
2. Ensure your host directory is writable by UID 1000:
   ```bash
   sudo chown -R 1000:1000 /path/to/local/directory
   ```
3. Or run the container with appropriate user mapping:
   ```bash
   docker run -u $(id -u):$(id -g) -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs
   ```

### Pandoc Fails with Font Errors

**Issue**: PDF generation fails with font-related errors

**Solution**:
1. The container includes Noto fonts, but you may need additional fonts:
   ```bash
   # Check available fonts
   fc-list
   
   # Install additional fonts by extending the container
   ```

### Large Document Processing Issues

**Issue**: Container runs out of memory when processing large documents

**Solution**:
1. Increase Docker's memory allocation in Docker Desktop settings
2. Run with memory limits:
   ```bash
   docker run --memory="4g" -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs
   ```

### TeXLive Compilation Fails

**Issue**: LaTeX compilation fails with missing packages

**Solution**:
1. The container includes a basic TeXLive installation with common packages
2. For additional packages, use `tlmgr`:
   ```bash
   docker run -it tsysdevstack/toolboxes-docs tlmgr install package-name
   ```

### Missing Language Runtime Tools

**Issue**: Tools installed via npm/pip not working

**Solution**:
1. The container uses `mise` to manage language runtimes
2. Check if the runtime is properly configured:
   ```bash
   mise current
   ```
3. Install or activate the required version:
   ```bash
   mise use --global python@3.12.6  # or required version
   ```

### Quarto Rendering Issues

**Issue**: Quarto fails with missing R or Python environments

**Solution**:
1. The container has a basic Python environment but may need extensions:
   ```bash
   # Install required Python packages
   pip3 install jupyter numpy pandas matplotlib
   ```

## 🔧 Diagnostic Commands

### Check Container Information
```bash
# Check running containers
docker ps

# Check container logs
docker logs <container-name>

# Execute commands in running container
docker exec -it <container-name> /bin/bash
```

### Verify Tool Availability
```bash
# Check all installed tools
docker run --rm tsysdevstack/toolboxes-docs which pandoc mdbook typst marp quarto jq yq

# Check Pandoc version and capabilities
docker run --rm tsysdevstack/toolboxes-docs pandoc --version

# Check TeXLive installation
docker run --rm tsysdevstack/toolboxes-docs xelatex --version
```

### Check Storage and Paths
```bash
# Verify output directory exists and is writable
docker run --rm -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs ls -la /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output

# Check if input files are accessible
docker run --rm -v $(pwd)/:/data tsysdevstack/toolboxes-docs ls -la /data
```

## 🔍 Debugging Steps

1. **Check the error message carefully**
2. **Verify your input files exist and are accessible**
3. **Check that you have sufficient disk space**
4. **Try running a simple command first** (e.g., `pandoc --version`)
5. **Check container logs** if running as a service
6. **Verify volume mappings are correct**
7. **Test with a minimal document** to isolate issues

## 📞 Support

If you encounter issues not covered in this guide:

1. Check the [Usage Guide](USAGE.md) for correct command syntax
2. Review [Cheat Sheet](CHEATSHEET.md) for common commands
3. Search the repository issues for similar problems
4. Create a new issue with:
   - Docker version
   - Host OS
   - Command used
   - Error message
   - Expected behavior