Troubleshooting

Overview

This guide covers common issues, error messages, and solutions across all Dex workflows.

Workspace and Setup Issues

Workspace setup canceled or missing

Symptom:

Dex prints workspace config errors or exits to setup guidance.

Cause: Workspace configuration (~/.config/dexdsl/workspaces.json) is missing or invalid.Solution:

dex setup --reset

This launches the interactive setup wizard to configure site and api repo roots.

TTY required error

Symptom:

Command requires TTY but running in non-interactive shell.

Cause: Commands like dex init, dex update, dex status, or dashboard features require an interactive terminal.Solution:

Run in an interactive terminal (not in CI/CD or redirected output)
Use non-TTY alternatives where supported:
- dex entry audit (non-interactive)
- dex assets validate (non-interactive)
- dex catalog validate (non-interactive)
- dex init --from seed.json (non-interactive with seed file)

DEX_WORKSPACE_FILE not found

Symptom:

Cannot read workspace config at /custom/path/workspaces.json

Cause: The DEX_WORKSPACE_FILE environment variable points to a non-existent file.Solution:

Check the environment variable:
```
echo $DEX_WORKSPACE_FILE
```
Either:
- Unset the variable: unset DEX_WORKSPACE_FILE
- Fix the path: export DEX_WORKSPACE_FILE=~/.config/dexdsl/workspaces.json
- Run setup: dex setup --reset

Entry Creation and Validation

Template not found

Symptom:

Template not found: ./custom-template.html

Cause: The specified template path doesn’t exist.Solution:

Verify the path:
```
ls -la ./custom-template.html
```
Use auto-detection (omit --template)

Use canonical template:

dex init --template ./entries/test-5/index.html

Template validation failed

Symptom:

Template validation failed; missing: dex-sidebar-config, dex-manifest

Cause: Template is missing required <script> tags with specific IDs:

dex-sidebar-config
dex-sidebar-page-config
dex-manifest

Solution: Ensure your template includes all required script blocks. Reference the canonical template:

cat entries/test-5/index.html | grep -E 'id="dex-'

Required structure:

<script id="dex-sidebar-config" type="application/json">...</script>
<script id="dex-sidebar-page-config" type="application/json">...</script>
<script id="dex-manifest" type="application/json">...</script>

Video URL required for non-interactive init

Symptom:

Video URL is required for non-interactive init. Pass --from with video.dataUrl.

Cause: Seed JSON file is missing video.dataUrl.Solution: Add video URL to seed file:

{
  "video": {
    "dataUrl": "https://vimeo.com/123456789",
    "dataUrlOriginal": "https://vimeo.com/123456789"
  }
}

Generated HTML failed sanitizer verification

Symptom:

Generated HTML failed sanitizer verification: [issues]

Cause: The generated HTML contains:

Forbidden runtime script hosts (squarespace, sqspcdn, legacysite)
Missing auth trio scripts
Legacy Auth0 blocks

Solution:

Use the canonical template:

dex init --template ./entries/test-5/index.html

If using a custom template, ensure it:
- Includes auth trio scripts:
  - /assets/vendor/auth0-spa-js.umd.min.js
  - /assets/dex-auth0-config.js or /assets/dex-auth-config.js
  - /assets/dex-auth.js
- Has no legacy Auth0 markers:
  - 
  - id="btn-login"
  - id="btn-profile-container"
- Has no external script sources from forbidden hosts

Schema validation failed

Symptom:

formatZodError(error, 'Sidebar config (wizard step)')
formatZodError(error, 'Manifest (wizard step)')
formatZodError(error, 'Entry data')

Cause: Data doesn’t match the expected schema.Common issues:

Missing required fields:
- lookupNumber
- attributionSentence
- credits.artist
Invalid bucket names (must be A, B, C, D, E, or X)
Malformed manifest structure
Invalid video mode (url or embed only)

Solution: Validate your seed file structure. Example valid seed:

{
  "title": "Artist Name — Title",
  "slug": "artist-name",
  "video": {
    "dataUrl": "https://vimeo.com/123456789"
  },
  "sidebarPageConfig": {
    "lookupNumber": "LOOKUP-0042",
    "buckets": ["A", "B"],
    "attributionSentence": "Recorded at Studio XYZ",
    "credits": {
      "artist": ["Artist Name"],
      "instruments": ["Instrument"],
      "year": 2025
    },
    "fileSpecs": {
      "bitDepth": 24,
      "sampleRate": 48000,
      "channels": "stereo"
    },
    "metadata": {
      "sampleLength": "3:45",
      "tags": ["tag1", "tag2"]
    }
  }
}

Entry Audit Failures

FAIL: missing required runtime marker

Symptom:

FAIL tim-feeney
  runtime: missing required marker: id="scroll-gradient-bg"

Cause: Generated HTML is missing required DOM elements:

id="scroll-gradient-bg"
id="gooey-mesh-wrapper"
class="dex-breadcrumb"

Solution: Regenerate from canonical template:

dex update
# Select the entry, save to regenerate

Or use doctor repair:

dex doctor
# Select entry, press Ctrl+S to repair

FAIL: invalid lookup token format

Symptom:

FAIL tim-feeney
  token error: invalid lookup token format

Cause: The lookupNumber field has an invalid format.Expected format:

LOOKUP-0042
lookup:LOOKUP-0042
Plain lookup numbers are also accepted

Solution: Update the entry:

dex update
# Select entry, fix lookupNumber field

Or edit entries/tim-feeney/entry.json directly:

{
  "sidebarPageConfig": {
    "lookupNumber": "LOOKUP-0042"
  }
}

FAIL: recording index token parse error

Symptom:

FAIL tim-feeney
  recording index: bundle token parse error

Cause: Invalid asset reference token in recording index fields:

recordingIndexPdfRef
recordingIndexBundleRef
recordingIndexSourceUrl

Expected formats:

Lookup ref: lookup:LOOKUP-0042
Asset ref: asset:1a2b3c4d5e6f
Bundle ref: bundle:1a2b3c4d5e6f
Source URL: Valid HTTP(S) URL

Solution: Correct the token format in entry metadata:

dex update
# Select entry, fix recording index refs

FAIL: forbidden runtime script host detected

Symptom:

FAIL tim-feeney
  forbidden host: https://squarespace.com/script.js

Cause: HTML contains scripts from forbidden hosts:

squarespace.com
squarespace-cdn.com
sqspcdn.com
legacysite.com

Solution: Remove legacy scripts:

Open update wizard:
```
dex update
```
Regenerate from canonical template
Or manually edit entries/tim-feeney/index.html to remove forbidden scripts

Catalog and Manifest Issues

Catalog manifest entry not found

Symptom:

catalog manifest entry not found: tim-feeney

Cause: The entry doesn’t exist in the staged manifest.Solution: Add it first:

dex catalog manifest add --entry tim-feeney

Catalog manifest patch requires resolvable entry_id

Symptom:

catalog manifest patch requires resolvable entry_id.

Cause: Dex cannot resolve the entry identifier from provided token or catalog.entries.json.Solution: Provide explicit --entry-id:

dex catalog manifest add \
  --entry tim-feeney \
  --entry-id entry-123 \
  --entry-href /entry/tim-feeney/

Catalog manifest remove blocked

Symptom:

catalog manifest remove blocked: linked entry page exists.
Use `dex catalog manifest retire --entry ...` or pass --force-remove.

Cause: Dex blocks removal when the entry page still exists to prevent broken links.Solution: Either:

Retire instead (recommended):

dex catalog manifest retire --entry tim-feeney

Force remove (if you’re sure):

dex catalog manifest remove --entry tim-feeney --force-remove

Spotlight entry not staged in manifest

Symptom:

catalog:validate warning spotlight entry entry-123 is not staged in manifest.

Cause: Spotlight references an entry not in the manifest.Solution: Add the spotlight entry to manifest:

dex catalog manifest add --entry entry-123

Home featured entry missing from catalog

Symptom:

catalog:validate warning home featured entry missing from catalog manifest: entry-124

Cause: Home featured list includes an entry not in the catalog.Solution: Either:

Add to catalog:

dex catalog manifest add --entry entry-124

Remove from home featured:

dex home featured set --entries entry-123,entry-125

Preflight and Deployment Issues

Preflight failed: no non-exempt entries audited

Symptom:

preflight failed: no non-exempt entries were audited.

Cause: No entries with entry.json exist in entries/.Solution:

Check entries directory:
```
ls -la entries/
```
Ensure entries have entry.json:
```
find entries/ -name "entry.json"
```
Create entries if missing:
```
dex init
```

Preflight failed: entry audit failures

Symptom:

preflight failed: entry audit failures (3/15) tim-feeney, jane-doe, old-entry

Cause: Some entries fail runtime validation.Solution:

Audit failing entries:
```
dex entry audit --slug tim-feeney
```

Fix issues and repair:

dex doctor
# Select and repair failing entries

Re-run preflight:
```
dex release preflight --env prod
```

Preflight failed: missing protected asset coverage

Symptom:

preflight failed: missing protected asset coverage (LOOKUP-0042, LOOKUP-0043)

Cause: Active catalog entries lack protected asset mappings.Solution:

Inspect coverage:

dex assets validate
dex entry audit --all --inventory-only

Add missing mappings in data/protected.assets.json:

{
  "LOOKUP-0042": {
    "pdf": "asset:1a2b3c4d5e6f",
    "bundle": "bundle:6f5e4d3c2b1a"
  }
}

Re-run preflight

Preflight failed: generated HTML secure check failure

Symptom:

preflight failed: generated HTML secure check failure

Cause: One or more entries have:

Legacy Auth0 blocks
Forbidden runtime script hosts
Missing auth trio

Solution:

dex doctor
# Repair all entries with warnings

Admin token/env mismatch

Symptom:

publish/diff auth failures against Worker admin endpoints

Cause: Admin token is not set or doesn’t match the Worker secret.Solution:

Confirm environment:

echo $DEX_CATALOG_ADMIN_TOKEN_TEST
echo $DEX_CATALOG_ADMIN_TOKEN_PROD

Export correct token:

export DEX_CATALOG_ADMIN_TOKEN_PROD="your-token"

Verify Worker secret exists:
```
wrangler secret list
```

Add secret if missing:

wrangler secret put DEX_CATALOG_ADMIN_TOKEN_PROD

Git push failed

Symptom:

Git push failed.
error: failed to push some refs to 'origin'

Cause: Local branch is behind remote or has conflicts.Solution:

git pull --rebase origin main
# Resolve any conflicts
git push origin main

Or use Dex deploy:

dex deploy --preflight-env prod

Detached HEAD is not deployable

Symptom:

Detached HEAD is not deployable. Check out a branch first.

Cause: You’re not on a branch (detached HEAD state).Solution:

git checkout main
dex deploy

Doctor and Repair Issues

Repair aborted: regenerated HTML failed sanitizer

Symptom:

Repair aborted; regenerated HTML failed sanitizer verification: [issues]

Cause: The template or entry data causes sanitizer failures.Solution:

Use canonical template:

dex doctor --template ./entries/test-5/index.html

Check entry metadata for forbidden patterns
Ensure entry.json is valid

Performance and Scale Issues

Entry audit taking too long

Symptom: Audit command hangs or takes minutes to complete.Cause: Many entries or slow disk I/O.Solution:

Audit specific entries only:
```
dex entry audit --slug tim-feeney
```
Use --inventory-only to skip runtime checks:
```
dex entry audit --all --inventory-only
```
Run in parallel for specific slugs (if scripting)

Debug Strategies

Enable Verbose Logging

Set environment variable:

export DEX_DEBUG=1
dex catalog validate

Inspect Generated Files

Check entry artifacts:

cat entries/tim-feeney/entry.json | jq .
cat entries/tim-feeney/manifest.json | jq .
grep -E 'id="dex-' entries/tim-feeney/index.html

Validate JSON Files

jq . data/catalog.editorial.json
jq . data/protected.assets.json
jq . data/catalog.entries.json

Check File Permissions

ls -la entries/tim-feeney/
chmod -R u+rw entries/

Getting Help

Check Documentation

Run Manual Verification

npm run verify:dex-manual

Verifies README contract matches actual commands.

Run Full Test Suite

npm run phase1:all
npm run sanitize:all

Common Gotchas

Wrong Working Directory

Dex auto-resolves to configured repo root, but some commands require running from project root

Stale Environment Variables

Token changes require restarting your shell or re-exporting variables

Workspace Config Stale

After moving repos, run dex setup --reset to update paths

Git State Issues

Detached HEAD, dirty working tree, or conflicts block deployment

Next Steps

If you’ve exhausted these solutions:

Check GitHub issues: dexdsl/dex-cli issues
Review commit history for recent breaking changes
Consult with team leads or file a support ticket
Run verification suite for contract validation

Get Started

Core Concepts

Guides

Troubleshooting

Overview

Workspace and Setup Issues

Entry Creation and Validation

Entry Audit Failures

Catalog and Manifest Issues

Preflight and Deployment Issues

Doctor and Repair Issues

Performance and Scale Issues

Debug Strategies

Enable Verbose Logging

Inspect Generated Files

Validate JSON Files

Check File Permissions

Getting Help

Check Documentation

Run Manual Verification

Run Full Test Suite

Common Gotchas

Wrong Working Directory

Stale Environment Variables

Workspace Config Stale

Git State Issues

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Overview

​Workspace and Setup Issues

​Entry Creation and Validation

​Entry Audit Failures

​Catalog and Manifest Issues

​Preflight and Deployment Issues

​Doctor and Repair Issues

​Performance and Scale Issues

​Debug Strategies

​Enable Verbose Logging

​Inspect Generated Files

​Validate JSON Files

​Check File Permissions

​Getting Help

​Check Documentation

​Run Manual Verification

​Run Full Test Suite

​Common Gotchas

Wrong Working Directory

Stale Environment Variables

Workspace Config Stale

Git State Issues

​Next Steps

Build docs developers (and LLMs) love

Overview

Workspace and Setup Issues

Entry Creation and Validation

Entry Audit Failures

Catalog and Manifest Issues

Preflight and Deployment Issues

Doctor and Repair Issues

Performance and Scale Issues

Debug Strategies

Enable Verbose Logging

Inspect Generated Files

Validate JSON Files

Check File Permissions

Getting Help

Check Documentation

Run Manual Verification

Run Full Test Suite

Common Gotchas

Next Steps