Troubleshooting

tdsl not found

If tdsl --help cannot be run after installation, check whether the installation directory is in your PATH.

which tdsl
tdsl --help

When using the install script, the default installation path is ~/.local/bin/tdsl.

export PATH="${HOME}/.local/bin:${PATH}"

Diagnosing syntax errors in .tdsl files

First, run check to perform syntax and semantic checking. Use ast if you want to inspect the parse result.

tdsl check sample.tdsl
tdsl ast sample.tdsl

Fixing lane reference and ID issues

lint detects undefined lane references, duplicate IDs, start > end, empty labels, and empty or duplicate tag elements. Items that can be safely fixed can be corrected with --fix.

tdsl lint sample.tdsl
tdsl lint sample.tdsl --fix

Use JSON format for CI or other tools.

tdsl lint sample.tdsl --format json

Unstable Wikidata fetching

If you want to avoid the effects of network or cache issues with files containing Wikidata imports, use --offline to process only static items.

tdsl build sample.tdsl --offline --pretty
tdsl render sample.tdsl --offline --output sample.html

Use --no-cache to re-fetch the latest data, or --cache-ttl <seconds> to change the cache TTL.

tdsl build sample.tdsl --no-cache --pretty
tdsl build sample.tdsl --cache-ttl 0 --pretty

Adjusting HTML appearance

Adjust the display options for render.

tdsl render sample.tdsl \
  --output sample.html \
  --scale 5 \
  --lane-height 80 \
  --theme dark

Use --custom-css to add custom CSS.

Warnings for items outside timeline.range

From v1.23.0 onwards, tdsl check / tdsl build / the LSP emit a warning when an event / span / event_range falls outside timeline.range (previously this was a silent drop/clip by the renderer, with no diagnostic).

• Event "{id}" at {time} is outside timeline.range and will not be rendered
• {Span|EventRange} "{id}" is entirely outside timeline.range and will not be rendered
• {Span|EventRange} "{id}" is partially outside timeline.range and will be clipped

If you are intentionally narrowing the displayed range, these can be ignored. Otherwise, expand timeline.range or fix the item's dates.

Errors/warnings for unknown unit / kind

From v1.23.0 onwards, specifying an unknown value for timeline.unit (anything other than year / month / day / hour / minute) is an error (previously it silently fell back to year). An unknown lane kind produces a warning instead, since kind is meant for free-form classification.

tdsl check sample.tdsl

Fix unit to one of year / month / day / hour / minute. Use kind custom; if you want to make a custom classification explicit.

The Playground fails to load WASM

The Playground runs WASM in the browser. If it stays on "Loading…" or nothing renders, first open the Console / Network tab in your browser's developer tools.

• Check that the WASM file request returns 200 and that the response Content-Type is application/wasm. If it is served as application/octet-stream or similar, the browser fails to streaming-compile it.
• Check that a corporate proxy or ad blocker is not blocking the .wasm request.
• Read the Console error message (CompileError / LinkError, etc.) as-is to tell whether the cause is network- or runtime-related.

The Playground shows stale results

If you see old results right after a deploy, the cause is caching.

• Hard reload (macOS: Cmd+Shift+R / Windows: Ctrl+Shift+R) to bypass the browser cache and refetch.
• If that does not help, clear the site's Cache Storage / Service Worker from the Application tab in developer tools.
• If you are trying new DSL syntax and hit a parse error, the WASM loaded by the Playground may be outdated. Confirm that the latest deployment is live.

Unsupported browsers

The Playground requires WebAssembly. It works in modern Chrome / Edge / Firefox / Safari, but not in environments where WebAssembly is disabled or in extremely old browsers.

• Update your browser to the latest version, or reopen the page in another modern browser.
• If a browser extension disables WebAssembly, turn it off.
• If you need it to run reliably on your machine, consider the browser-independent CLI (tdsl render).