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.

---

## Project Files Not Auto-Loading

### Problem Description

**Symptoms:**
- Uploaded project.json but CSV/SVG/CSS files don't load
- Have to manually select each file individually
- Timeline doesn't render after selecting project.json

### Solution

This is expected behavior due to browser security restrictions. When you upload a single project.json file, the browser doesn't allow automatic access to other files in the same directory.

**Use the Folder Picker (Recommended):**

1. Click **"📂 Load Project Folder"** (blue button at top of file manager)
2. Select the entire project folder
3. All files will be loaded automatically

This works because you're explicitly granting permission to access all files in the folder.

**Alternative:** Load files individually using the separate upload buttons for CSV, SVG, and CSS.

**For developers running from local server:** Files auto-load when served via HTTP (no manual upload needed).

---

## 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.