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
CORS errors when opening index.html	make serve or python3 -m http.server 8000	CORS Errors
"Template is missing required elements"	Check <defs> section has all 3 template IDs	Template Validation
CSV loads but shows 0 valid items	Verify fieldMapping matches CSV column names	CSV Data Not Loading
Tests failing or timing out	make clean && make install	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:

make install

Manual Fix:

If not using the Makefile, set the NODE_OPTIONS environment variable before running npm:

export NODE_OPTIONS="--openssl-legacy-provider"
npm install

Permanent Fix (for your shell session):

Add to your ~/.bashrc or ~/.zshrc:

export NODE_OPTIONS="--openssl-legacy-provider"

Then reload your shell:

source ~/.bashrc

Step-by-Step Recovery

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

1. Clean everything:

   rm -rf node_modules package-lock.json
   npm cache clean --force
   

2. Install with workaround:

   export NODE_OPTIONS="--openssl-legacy-provider"
   npm install
   

3. Verify installation:

   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:

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

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:

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

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

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

   <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:

Task_ID,Task_Name,Due_Date,Epic

Your project.json must have:

{
  "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:

   make clean
   make install
   

2. Check Node.js version:

   node --version  # Should be v22+ or v24+
   

3. Run specific test file:

   npm test test/generator.test.js
   

4. Check test environment:

   cat vitest.config.js
   

   Should show environment: 'jsdom'

5. Clear Vitest cache:

   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:

   # Open browser to http://localhost:8000
   # Example project should auto-load successfully
   

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