← Troubleshooting guides

How to fix path references that do not resolve

How-To Troubleshooting Beginner 1191005HOWTO-1191005

HOWTO-1191005TroubleshootingBeginner

This guide shows you how to fix SpecDD path references that do not resolve.

Missing exact paths are unresolved references, not .sdd syntax errors. The fix is usually to correct the path, open the right content root, update a stale reference, or make the line plain prose when it was not meant to be a path.

Short answer

SpecDD treats only explicit path prefixes as file references: ./, ../, and /. Check whether the reference is meant to be a path, resolve it from the current spec directory or selected content root, fix renamed or moved files, check case sensitivity, and validate with editor diagnostics or specdd lint.

Steps

1. Confirm the reference is meant to be a path

This is prose, not a path reference:

Owns:
  itinerary.js

Use an explicit path when you want tools to resolve it:

Owns:
  ./itinerary.js

If the line is only descriptive prose, leave it unprefixed.

2. Use an explicit path prefix

Supported path prefixes are:

Unsupported:

Can read:
  ~/shared/spec.sdd

Use a project-relative or spec-relative path instead.

3. Check the reference base

For this spec:

src/trips/itinerary.sdd

this path:

Can read:
  ../storage/trip-storage.sdd

resolves from src/trips/, not from the repository root.

Paths starting with / resolve from the selected content root:

References:
  /src/storage/trip-storage.sdd

If the wrong root is open, / paths can appear broken.

4. Check moved or renamed files

Unresolved references often come from stale paths after a refactor:

References:
  ../storage/trip-store.sdd

If the file is now:

../storage/trip-storage.sdd

update the reference.

5. Check case and monorepo root

Case matters on many filesystems and in tools. Make the path match the actual filename:

TripStorage.sdd

is not the same as:

trip-storage.sdd

In monorepos, confirm which directory is the selected SpecDD content root. A / path resolves from that root, not necessarily from the Git repository root if the project has independent SpecDD roots.

6. Fix malformed globs

Malformed globs are warning-level unresolved glob issues, not syntax errors.

Problem:

Can read:
  ./fixtures/[*.json

Fix:

Can read:
  ./fixtures/*.json

7. Validate with editor or CLI

Run:

specdd lint path/to/spec.sdd

or use editor path warnings. The unresolved reference should disappear after the path is corrected.

Common causes

How to verify the fix

The path is fixed when:

← Troubleshooting guides