What causes "artifact {relative} has invalid reference path" in affaan-m/ECC?

Set reference_path to the non-empty relative path of the actual reference file for that source

affaan-m/ECC · error · ContractError

artifact has invalid reference path

Error message

artifact {relative} has invalid reference path

What it means

Each provenance source inside a receipt entry must have a 'reference_path' that is a non-empty string. This error is raised when reference_path is missing, null, not a string, or an empty string. It ensures every cited source points to an identifiable reference file.

Solutions

Set reference_path to the non-empty relative path of the actual reference file for that source
Fix key-name typos so the field is exactly 'reference_path'
Regenerate the receipt via the tasteforge pipeline to produce well-formed provenance
Ensure the JSON serialization step is not converting empty paths to ''

Example fix

# before
{'reference_sha256': 'a'*64, 'time_basis': 'whole_file'}
# after
{'reference_path': 'refs/intro.mp4', 'reference_sha256': 'a'*64, 'time_basis': 'whole_file'}

Defensive patterns

Strategy: validation

Validate before calling

for src in entry.get('provenance', []):
    rp = src.get('reference_path')
    assert isinstance(rp, str) and rp, f'invalid reference_path: {rp!r}'

Type guard

def valid_reference_path(src: dict) -> bool:
    rp = src.get('reference_path')
    return isinstance(rp, str) and len(rp) > 0

Try / catch

try:
    validate_artifact_receipt(out_dir)
except ContractError as e:
    if 'invalid reference path' in str(e):
        fix_or_regenerate_receipt()
    else:
        raise

Prevention

Use exact field name 'reference_path' via a shared schema/dataclass
Validate receipt JSON against a JSON Schema before submission
Avoid manual JSON editing; use helper scripts that guarantee field presence
Watch for serializers coercing None to ''

When it happens

Trigger: validate_artifact_receipt iterating a provenance list and finding a source dict without a valid reference_path — e.g. hand-edited receipt, a generator emitting reference_path: None, or a typo'd key like referencePaths.

Common situations: Manual receipt authoring with key-name typos, JSON tools serializing empty strings, scripts that substitute None when a reference path variable is unset, migrating receipts between schema versions.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/f4e404dadf00c4fb. Report an issue: GitHub.

Appendix: source

Thrown at skills/taste-application/scripts/tasteforge/contract.py:411

            raise ContractError(f"artifact path escapes output directory: {relative}") from error
        if entry.get("provider_execution") is not False:
            raise ContractError(f"artifact {relative} permits provider execution")
        if not isinstance(entry.get("genre_numbers"), list):
            raise ContractError(f"artifact {relative} lacks genre binding")
        modalities = entry.get("modalities")
        if (not isinstance(modalities, list)
                or any(modality not in _REQUIRED_MODALITIES for modality in modalities)):
            raise ContractError(f"artifact {relative} has invalid modality binding")
        if entry.get("bytes") != path.stat().st_size:
            raise ContractError(f"artifact {relative} byte size does not match receipt")
        if entry.get("sha256") != _sha256(path):
            raise ContractError(f"artifact {relative} SHA-256 does not match receipt")
        provenance = entry.get("provenance")
        if not isinstance(provenance, list) or not provenance:
            raise ContractError(f"artifact {relative} lacks exact reference/time provenance")
        for source in provenance:
            if not isinstance(source.get("reference_path"), str) or not source["reference_path"]:
                raise ContractError(f"artifact {relative} has invalid reference path")
            digest = source.get("reference_sha256")
            if not isinstance(digest, str) or len(digest) != 64:
                raise ContractError(f"artifact {relative} has invalid reference SHA-256")
            if (source["reference_path"], digest) not in known_sources:
                raise ContractError(f"artifact {relative} cites an unknown provenance source")
            times = source.get("reference_times")
            basis = source.get("time_basis")
            if not isinstance(times, list) or basis not in {"media_seconds", "whole_file"}:
                raise ContractError(f"artifact {relative} has invalid reference/time provenance")
            if basis == "media_seconds" and not times:
                raise ContractError(f"artifact {relative} lacks media reference times")
            if basis == "whole_file" and times:
                raise ContractError(f"artifact {relative} whole-file provenance must not invent times")
            if basis == "media_seconds":
                expected_duration = source_durations.get((source["reference_path"], digest))
                if expected_duration is None or source.get("source_duration") != expected_duration:
                    raise ContractError(f"artifact {relative} has an unbound source duration")
                for time in times:

View on GitHub (pinned to 8321021c54)