Skip to content

Troubleshooting

Common problems when installing, running, or authoring DTCS contracts.

Installation

pip install dtcs tries to compile from source

Pre-built wheels are published for common platforms and Python 3.9–3.13. If pip falls back to a source build:

  1. Ensure you are on a supported Python version.
  2. Install Rust 1.75+ and maturin.
  3. Or pin a released version: pip install dtcs==0.13.0.

See faq.md.

dtcs: command not found after pip install

The dtcs CLI should be on your PATH after pip install dtcs. If not:

python -m dtcs version

Add your Python scripts directory to PATH, or use python -m dtcs in scripts and CI.

cargo install dtcs is slow

cargo install compiles from source. This is normal on first install. Subsequent updates reuse the cargo cache.

Path and working directory

Example commands fail with "file not found"

Most repository examples assume you run commands from the repository root:

dtcs validate examples/minimal.dtcs.yaml
# or: examples/customer_pipeline.dtcs.yaml

If you are in the examples/ directory, adjust paths or return to the repo root. See examples/README.md.

dtcs run --input file not found

The --input path is relative to your current working directory. Clone the repository or provide an absolute path to your input JSON.

Pip-only installs do not include examples/ or tests/fixtures/. Use the curlable sample in getting-started.md, clone the repository, or author your own files.

Validation errors

Run diagnostics for structured output:

dtcs diagnostics my_contract.yaml
dtcs diagnostics my_contract.yaml --json
Diagnostic Likely cause Fix
dtcs:unsupported-version dtcsVersion not in the supported set Set dtcsVersion: "3.0.0" (preferred) or "2.0.0" / "1.0.0" / "1.0.0-draft" (patch variants like 1.0.1 / 2.0.1 / 3.0.1 are rejected)
dtcs:missing-lineage Output without lineage mapping Add lineage.mappings entry for each output
dtcs:unresolved-reference Field path does not exist Use interface.field format matching an input/output id
dtcs:invalid-type Malformed type expression Use list<string>, not bare list
dtcs:unknown-registry-entry Unrecognized dtcs: identifier Run dtcs registry list; use embedded stdlib identifiers
dtcs:invalid-semantic-action Dataset action missing parameters, or bad target See Appendix A; supply fields / join keys / etc.
stdlib semantics errors Wrong target type, nullability, or rule phase Run dtcs registry resolve dtcs:IDENTIFIER --json

Unexpected lineage operation / flow after round-trip

From 0.11.0, omitted lineage operation defaults to dtcs:derive and flow defaults to derived. Plan JSON goldens and dtcs plan --json may show these fields even when your YAML omitted them. This is intentional.

Runtime treats missing fields as null

Missing and null are distinct. Inspect JSON for {"$dtcs":"missing"} vs null. Use dtcs:is_missing / dtcs:is_null in expressions. See faq.md and expressions.md.

See writing-contracts.md for more diagnostic fixes. Upgrading tools: migration-0.13.md. Historical 0.12 / Spec 2.0: migration-0.12.md. From 0.10.x to 0.11.x: migration-0.11.md.

Analysis and planning

dtcs analyze exits non-zero on a valid contract

analyze requires a valid contract and no error-severity analysis diagnostics. Warnings may still appear. Run with --json to inspect validation and analysis sections separately.

dtcs plan fails after validate succeeds

Planning also requires static analysis to pass. Run dtcs analyze first and fix expression or semantics errors.

Python API

KeyError on runtime_execute result

dtcs.runtime_execute returns an envelope, not a flat output map:

result = dtcs.runtime_execute(execution_plan, inputs)
outputs = result["outputs"]  # not result["customer_clean"]

The CLI dtcs run --json emits a flat output map. See json-output.md.

Contract dict keys rejected

Python contract dicts must use camelCase keys (dtcsVersion, semanticActions), matching the Canonical Object Model. See json-output.md.

is_valid on wrong object

dtcs.is_valid checks a diagnostic report ({"diagnostics": [...]}). For runtime_execute, pass the full result or check result["outputs"] separately.

CI integration

See ci-integration.md for validate/analyze/compat gates with JSON parsing.

Getting help

  • FAQ
  • GitHub issues — include dtcs version, the command run, and dtcs diagnostics --json output
  • SPEC.md for normative behavior