Troubleshooting

Symptom → cause → fix for common odcs / pyodcs issues. For installation-only problems, see Installation — Troubleshooting.

Installation

Symptom	Likely cause	Fix
odcs: command not found	Binary not on PATH	cargo install odcs; add ~/.cargo/bin to PATH
pyodcs import fails after clone	Editable install not built	maturin develop --features python --locked
PackageNotFoundError: pyodcs	Importing from source without install	pip install pyodcs or maturin develop
Version mismatch vs docs	Docs track main; registries may lag	See Release status
CI behaves differently than local	Unpinned tool version	Pin cargo install odcs --version 0.9.1 --locked

Validation failures

Symptom	Code	Fix
Unknown field at root or nested	odcs:unknown-field	Remove typo or use customProperties; see FAQ
Wrong ODCS spec version	odcs:unsupported-version	Set apiVersion: "v3.1.0" (not version)
Empty contract id	odcs:missing-required-field	Set non-empty id
Wrong document kind	odcs:invalid-kind	Set kind: "DataContract"
Legacy metric not_null	odcs:invalid-quality	Use nullValues, missingValues, etc.
Quality at contract root	odcs:unknown-field or schema error	Move quality under schema[]
Duplicate YAML/JSON key	odcs:duplicate-key	Remove duplicate; check path in object_ref (exit code 2)
JSON Schema constraint	odcs:json-schema-violation	Run odcs diagnostics file.yaml --json; compare with odcs schema
Relationship endpoint invalid	odcs:unresolved-reference	Fix from / to under schema[].relationships
Duplicate schema object name	odcs:invalid-schema	Use unique schema[].name values (phase: structural)
Duplicate server identifier	odcs:invalid-schema	Use unique servers[].server values (phase: structural)
SLA element references missing schema	odcs:unresolved-reference	Set slaProperties[].element / slaDefaultElement to existing schema[].name
Quality rule missing type	odcs:invalid-quality	Set type or add metric, query, or engine
Server typo (e.g. sever)	odcs:unknown-field	Fix field name; use server at object root

Exit codes

Code	Meaning	Typical cause
0	Valid	—
1	Validation errors	Semantic/structural issues after parse
2	Parse or I/O failure	Malformed YAML/JSON, duplicate keys, missing file

version vs apiVersion

Field	Purpose	Example
version	Your contract revision	"1.0.0"
apiVersion	ODCS specification release	"v3.1.0"

Setting version: "3.1.0" does not select the ODCS spec — use apiVersion.

Duplicate-key limitations (0.5.0+)

Nested duplicates in block-style YAML and JSON are detected. Not fully scanned:

• YAML flow mappings ({key: value})
• YAML anchors and aliases (&anchor, *alias)

Use block-style YAML in CI. See Diagnostics — Duplicate-key limitations.

Symptom	Likely cause	Fix
FQN references not checked in CI	Validated without --registry or --dep	Index and pass --registry, or use --dep
registry entry not found	Stale or missing index	Run odcs registry index <dir>
Index fails on duplicate (id, version)	Two files share the same identity	Use unique pairs or separate registry roots
Index fails on symlink	Path escapes registry root	Remove or replace symlink
Parallel index jobs corrupt index	Concurrent registry index on same dir	Serialize index step in CI

Upgrading from older releases

Contracts that passed 0.2.x or 0.3.x may fail under 0.4.0+ (JSON Schema always on) or 0.5.0 (duplicate keys). See Migration.

Still stuck?

1. Run odcs diagnostics contract.yaml --json for structured output
2. Check FAQ and Diagnostics reference
3. Walk through Fix your first invalid contract
4. Open a GitHub issue with the diagnostic JSON (redact sensitive data)

Security

Report vulnerabilities per SECURITY.md — do not file public issues for security-sensitive reports.