Troubleshooting Playbook

Use this page as the film room after a broken possession. Start with the artifact or command named in the failure, then work the shortest route back to a clean rerun.

Dead-ball triage

Use the narrowest recovery loop

1. Regenerate or reopen the exact artifact named in the failure.
2. Inspect the JSON or Markdown output, not just the terminal text.
3. Fix the local cause first.
4. Rerun the narrowest failing command before you escalate to a wider pipeline command.

Dependency inventory artifact (dependency-inventory.json)

Best for: missing lockfiles, missing docs package paths, or suspicious environment surface.

1) Generate

uv run python -m nbadb.core.dependency_inventory --project-root . --output artifacts/health/local/dependency-inventory.json

2) Diagnose

python - <<'PY'
import json

data = json.load(open("artifacts/health/local/dependency-inventory.json"))
print("summary:", data["summary"])
print("lockfile_present:", data["lockfile"]["present"])
print("pyproject_present:", data["pyproject"]["present"])
print("docs_package_present:", data["docs_package"]["present"])
PY

3) Remediate

• If lockfile_present is false, run uv sync (or provide --lock-path) and commit the lockfile used by CI.
• If docs_package_present is false, run from repo root or pass --docs-package-path /abs/path/docs/package.json.
• If summary.package_count is unexpectedly low, check --project-root and rerun with an absolute path.

Data-quality JSON artifact (data-quality-report.json)

Best for: empty tables, failing checks, or “database not found” quality runs.

1) Generate

uv run nbadb run-quality --report-path artifacts/health/local/data-quality-report.json

2) Diagnose

python - <<'PY'
import json

report = json.load(open("artifacts/health/local/data-quality-report.json"))
print("summary:", report["summary"])
print("failed:", [r["message"] for r in report["results"] if not r["passed"]][:10])
PY

3) Remediate

• If you see Error: database not found. Run 'nbadb init' first., seed the data directory first with nbadb init or nbadb download plus a refresh command.
• If summary.total is 0, verify the DuckDB file exists at the configured --data-dir.
• If checks fail, inspect the reported tables/columns and rerun the refresh command that matches the scope you need (daily, monthly, or full).

Known issue: nbadb run-quality reports failed checks but does not fail the process when checks ran. Gate on summary.failed > 0 in CI if strict enforcement matters.

Endpoint coverage artifacts (artifacts/endpoint-coverage/*)

Best for: extractor/staging drift and runtime coverage gaps.

1) Generate

uv run nbadb extract-completeness

# Source coverage gate
uv run nbadb extract-completeness --require-full

# Source + model-contract gate
uv run nbadb extract-completeness --require-full --require-model-contract

By default this writes:

• artifacts/endpoint-coverage/endpoint-coverage-matrix.json
• artifacts/endpoint-coverage/endpoint-coverage-summary.json
• artifacts/endpoint-coverage/endpoint-coverage-report.md

Use --output-dir to write artifacts elsewhere.

The summary distinguishes source coverage from model ownership. In practice that lets you separate "we are not extracting or staging this surface" from "we land it, but we still need a downstream transform or an explicit exclusion." It also reports star_schema_coverage, which answers a different question: "the transform exists, but do we have a schema-backed final-tier contract for its output?"

2) Diagnose

python - <<'PY'
import json

summary = json.load(open("artifacts/endpoint-coverage/endpoint-coverage-summary.json"))
print("runtime:", summary["runtime_version"], "classes:", summary["runtime_endpoint_class_count"])
print("coverage:", summary["coverage"])
print("star_schema_coverage:", summary.get("star_schema_coverage", {}))
PY

3) Remediate

• If runtime_version is unknown or the class count is 0, make sure nba_api is installed in the active environment.
• If runtime_gap is high, validate runtime references in src/nbadb/extract/stats/*.py and endpoint names in src/nbadb/orchestrate/staging_map.py.
• If extractor_only rows appear, either add the endpoint to the staging map or normalize the coverage aliasing.
• If schema_missing_transform_outputs is non-zero, the pipeline is producing transform outputs without a matching nbadb.schemas.star contract. Treat that as a data-modeling gap, not an extractor/staging gap.

Docs-autogen artifacts (docs/content/docs/*)

Best for: generated docs drift, stale auto pages, or docs build failures after schema changes.

1) Generate

uv run nbadb docs-autogen --docs-root docs/content/docs

2) Expect these generated files

• schema/{raw,staging,star}-reference.mdx
• data-dictionary/{raw,staging,star}.mdx
• diagrams/er-auto.mdx
• lineage/lineage-auto.mdx
• lineage/lineage.json

3) Diagnose + remediate

• If command output does not show updated: or unchanged:, make sure you are running from repo root and the environment has docs-gen dependencies installed.
• If only unchanged: appears after schema edits, confirm that metadata actually changed in nbadb.schemas.*.
• If generated docs exist but the docs app still fails, verify the docs workspace dependencies and build path used by your environment.

Kaggle and common CLI/CI misses

Best next move after a fix

1. Rerun the narrowest failing command first.
2. Re-open the generated artifact or report, not just the terminal output.
3. Only rerun a wider pipeline command once the local symptom has actually cleared.

Related routes

• CLI Reference for exact command behavior
• Daily Updates for recurring run-mode choices
• Kaggle Setup for publish/download flows