Troubleshooting

make doctor reports a missing sibling telemetry checkout

Clone pldelisle/telemetry beside this repository, not inside it. The locked source is ../telemetry; moving it elsewhere changes dependency identity and requires an intentional pyproject.toml and lockfile update.

uv lock --check fails

The dependency declaration and uv.lock disagree. Run make lock, inspect both the lock diff and the resolved telemetry source, then rerun make doctor. Do not hand-edit the lockfile.

Imports resolve from an unexpected environment

Run make doctor, then use uv run --frozen ... or a Make target. Direct python, pytest, Ruff, or mypy invocations can silently use a different interpreter.

PostgreSQL tests skip

This is expected in the fast local suite. Create a disposable database, set TEST_CONTROL_DATABASE_URL, and run make test-postgres. The target refuses an absent URL because the fixtures drop and recreate service or generated-source tables.

Generated-source Compose validation reports a missing password

compose.generated-source.yaml requires GENERATED_SOURCE_POSTGRES_PASSWORD for a real run. Put it in the repository's gitignored .env file as described in the generated source guide. make compose-check uses a check-only value for syntax validation; it does not create a database.

PostgreSQL generated-source provisioning is slow

Check the selected profile first: development contains 50 million views and 2 million purchases. The one-pass CLI computes canonical hashes during COPY, then reads the staging tables back for independent verification. It loads tables in sequence, with one generator feeding the configured workers for each table. Raising --workers can help database writes but cannot accelerate that producer or the single largest table's digest. Use smoke for a quick functional check; keep the profile and worker count fixed when comparing timings. A materialization receipt proves content equality, not a performance qualification.

A generated-source replacement fails

Without --replace, existing generated-source tables cause an intentional error. With --replace, a failed load leaves the previous published tables available; inspect the error before retrying. Failed staging cleanup is best effort, so inspect for tables beginning with recommendations_load_ in the destination schema if a failure also interrupted cleanup. Do not remove unfamiliar tables or use docker compose down --volumes as a routine retry step.

The installed-wheel smoke test fails

Inspect .build/smoke-report.json when present. Confirm Python 3.14 is available, the sibling telemetry checkout matches the lock, and imports are not supplied through PYTHONPATH or user site packages. make smoke clears and recreates its generated package and virtual-environment state.

Compose validation or simulation fails

Confirm Docker Desktop is running and docker info succeeds. Use make compose-check for resolved configuration errors, then follow the bounded reset/start workflow in commerce-simulation-harness.md. Treat named volumes as local test state; inspect before removing them.

CI cannot check out telemetry

The current repository token does not grant cross-repository private access. Configure TELEMETRY_REPOSITORY_TOKEN as a read-only fine-grained token or GitHub App token with contents read access to pldelisle/telemetry. Do not place the token in workflow YAML, runner configuration logs, or repository files.

A self-hosted job never starts

Verify that the runner is online and has the exact labels self-hosted, macOS, and ARM64. Label matching is conjunctive. A lowercase or custom label does not satisfy a different label in the workflow.