timeline-svg/TROUBLESHOOTING.md

# Troubleshooting Guide

This document provides solutions to common issues encountered when developing with TimelineSvg.

## Quick Reference

| Problem | Quick Fix | See Section |
|---------|-----------|-------------|
| `npm install` fails with SSL cipher errors in WSL | `export NODE_OPTIONS="--openssl-legacy-provider" && npm install` | [npm Install Failures](#npm-install-failures-in-wsl-with-nodejs-v24) |
| CORS errors when opening index.html | `make serve` or `python3 -m http.server 8000` | [CORS Errors](#cors-errors-when-loading-timeline) |
| "Template is missing required elements" | Check `<defs>` section has all 3 template IDs | [Template Validation](#template-validation-errors) |
| CSV loads but shows 0 valid items | Verify `fieldMapping` matches CSV column names | [CSV Data Not Loading](#csv-data-not-loading) |
| Tests failing or timing out | `make clean && make install` | [Tests Failing](#tests-failing) |

---

## npm Install Failures in WSL with Node.js v24

### Problem Description

**Symptoms:**
- `npm install` fails with error: `ERR_SSL_CIPHER_OPERATION_FAILED`
- Error message contains: `Provider routines:ossl_gcm_stream_update:cipher operation failed`
- May also see `ETXTBSY` (text file busy) errors during esbuild installation
- Occurs specifically in WSL (Windows Subsystem for Linux) environments
- Appears with Node.js v24.x

**Error Example:**
```
npm error code ERR_SSL_CIPHER_OPERATION_FAILED
npm error C09CD49A5C750000:error:1C800066:Provider routines:ossl_gcm_stream_update:cipher operation failed:../deps/openssl/openssl/providers/implementations/ciphers/ciphercommon_gcm.c:346:
```

### Root Cause

Node.js v24 upgraded to OpenSSL 3.x, which introduced stricter cipher requirements and different default providers. When running in WSL, there's a compatibility issue between:
- Node.js v24's OpenSSL 3.x implementation
- WSL's kernel/filesystem handling of cryptographic operations
- npm's package extraction process (which uses encryption for tar.gz files)

The cipher operation fails during package decompression, preventing successful installation.

### Solution

**Quick Fix (Recommended):**

Use the provided Makefile, which includes the workaround:
```bash
make install
```

**Manual Fix:**

If not using the Makefile, set the `NODE_OPTIONS` environment variable before running npm:
```bash
export NODE_OPTIONS="--openssl-legacy-provider"
npm install
```

**Permanent Fix (for your shell session):**

Add to your `~/.bashrc` or `~/.zshrc`:
```bash
export NODE_OPTIONS="--openssl-legacy-provider"
```

Then reload your shell:
```bash
source ~/.bashrc
```

### Step-by-Step Recovery

If you're in a broken state with partial installation:

1. **Clean everything:**
   ```bash
   rm -rf node_modules package-lock.json
   npm cache clean --force
   ```

2. **Install with workaround:**
   ```bash
   export NODE_OPTIONS="--openssl-legacy-provider"
   npm install
   ```

3. **Verify installation:**
   ```bash
   npm test
   ```

   Should show: `58 passed (58)` across 3 test files

### Alternative Solutions

**Option A: Use Node.js v22 (LTS)**

If you don't need Node.js v24 features:
```bash
# Using nvm (Node Version Manager)
nvm install 22
nvm use 22
npm install
```

Node.js v22 uses OpenSSL 1.1.1 and doesn't have this issue.

**Option B: Use npm's legacy peer deps flag**

Sometimes combining flags helps:
```bash
export NODE_OPTIONS="--openssl-legacy-provider"
npm install --legacy-peer-deps
```

### Prevention

**For New Projects:**

Update your project's documentation and Makefile to include the workaround automatically. See the current `Makefile` for reference.

**For CI/CD:**

Add to your CI configuration:
```yaml
# GitHub Actions example
env:
  NODE_OPTIONS: "--openssl-legacy-provider"

# GitLab CI example
variables:
  NODE_OPTIONS: "--openssl-legacy-provider"
```

### Verification

After applying the fix, verify with:

```bash
# Check Node.js version
node --version  # Should show v24.x.x

# Check installation succeeded
ls -la node_modules | head -5

# Run tests to confirm everything works
npm test

# Expected output:
# ✓ Test Files  3 passed (3)
# ✓ Tests  58 passed (58)
```

### Related Issues

- **esbuild ETXTBSY errors**: Often occur together with SSL cipher errors. The same solution fixes both.
- **Vitest installation failures**: Vitest depends on esbuild, so the fix resolves Vitest installation issues too.

### When This Won't Help

This solution specifically addresses Node.js v24 + OpenSSL 3.x + WSL issues. It won't help with:
- Network connectivity problems (check `npm config get registry`)
- Permissions issues (avoid `sudo npm install`, use `nvm` instead)
- Disk space problems (check with `df -h`)
- Corrupted npm cache (run `npm cache verify`)

---

## CORS Errors When Loading Timeline

### Problem Description

**Symptoms:**
- Opening `index.html` directly in browser (file:// protocol)
- Console shows CORS errors when trying to load CSV, CSS, or SVG files
- Timeline doesn't render, shows "Keine Timeline verfügbar"

### Solution

Serve the application via HTTP:

```bash
# Using the Makefile (recommended)
make serve

# Or manually with Python 3
python3 -m http.server 8000

# Or with Python 2
python -m SimpleHTTPServer 8000

# Or with Node.js/npx
npx serve -l 8000
```

Then open: `http://localhost:8000`

### Why This Happens

Browsers enforce CORS (Cross-Origin Resource Sharing) restrictions on `file://` URLs for security. Loading external resources (CSV, CSS, SVG) requires HTTP protocol.

---

## Template Validation Errors

### Problem Description

**Symptoms:**
- Error: "Template is missing required elements: month-template"
- Error: "Failed to extract template element"
- Template renders but with empty placeholders

### Solution

**Check template structure:**

1. Open your `template-v2.svg` in a text editor
2. Verify it has a `<defs>` section
3. Ensure all three required template elements exist:
   ```svg
   <defs>
     <g id="month-template" style="display:none">...</g>
     <g id="lane-template" style="display:none">...</g>
     <g id="item-template" style="display:none">...</g>
   </defs>
   ```

4. Check that IDs are exactly as shown (case-sensitive)
5. Verify templates contain proper placeholders (e.g., `{{MONTH_X}}`, `{{LANE_NAME}}`)

**Common mistakes:**
- Template elements outside `<defs>` section
- Incorrect `id` attributes (e.g., `month_template` instead of `month-template`)
- Missing `style="display:none"` (causes templates to show in output)
- Malformed XML/SVG (unclosed tags)

**Quick fix:**

Copy a working template from `example/template-v2.svg` and modify it.

See `TEMPLATE_V2_GUIDE.md` for comprehensive template documentation.

---

## CSV Data Not Loading

### Problem Description

**Symptoms:**
- CSV file loads but no items appear
- Debug panel shows "Valid Items: 0"
- Console shows "Keine gültigen Items gefunden"

### Solution

**Check field mappings:**

1. Open debug panel in the UI (should show automatically)
2. Compare "CSV Structure Preview" headers with "Field Mapping"
3. Ensure `project.json` field mappings match your CSV column names exactly

**Example:**

If your CSV has:
```csv
Task_ID,Task_Name,Due_Date,Epic
```

Your `project.json` must have:
```json
{
  "fieldMapping": {
    "id": "Task_ID",
    "title": "Task_Name",
    "lane": "Epic",
    "due": ["Due_Date"]
  }
}
```

**Check date formats:**

Supported formats:
- `YYYY-MM-DD` (e.g., `2025-12-31`)
- `YYYY/MM/DD` (e.g., `2025/12/31`)
- `DD.MM.YYYY` (e.g., `31.12.2025`)

Unsupported formats will cause items to be filtered out.

### Verification

Look at the debug panel:
- "Parsed Rows" should match your CSV row count
- "Valid Items" should equal "Parsed Rows" (or close to it)
- If they differ significantly, check date formats and required fields

---

## Tests Failing

### Problem Description

**Symptoms:**
- `npm test` fails with errors
- Tests timeout or hang
- jsdom errors

### Solution

**Basic troubleshooting:**

1. **Reinstall dependencies:**
   ```bash
   make clean
   make install
   ```

2. **Check Node.js version:**
   ```bash
   node --version  # Should be v22+ or v24+
   ```

3. **Run specific test file:**
   ```bash
   npm test test/generator.test.js
   ```

4. **Check test environment:**
   ```bash
   cat vitest.config.js
   ```
   Should show `environment: 'jsdom'`

5. **Clear Vitest cache:**
   ```bash
   rm -rf .vitest node_modules/.vitest
   npm test
   ```

### Expected Test Results

All tests passing:
```
✓ test/generator.test.js (36 tests)
✓ test/engine.test.js (7 tests)
✓ test/integration.test.js (15 tests)

Test Files  3 passed (3)
Tests  58 passed (58)
```

---

## Need More Help?

1. Check existing documentation:
   - `README.md` - Overview and features
   - `TEMPLATE_V2_GUIDE.md` - Template creation and customization
   - `CLAUDE.md` - Architecture and development guide

2. Enable debug mode:
   - Debug panel shows automatically when loading projects
   - Check browser console for detailed error messages

3. Verify file paths:
   - All paths in `project.json` are relative to the project folder
   - Use forward slashes (`/`) not backslashes (`\`)

4. Test with example project:
   ```bash
   # Open browser to http://localhost:8000
   # Example project should auto-load successfully
   ```

   If example works but your project doesn't, compare configurations.