Troubleshooting#

Level: Beginner to Expert

You will: identify installation, configuration, service, data, and resume

failures from the first useful error message. Before you start: the guide that led to the failure.

Services: Follow the service requirements of the failing workflow.

Installation and optional extras#

Install the base package first, then add only the integration you need:

poetry install
poetry install -E ml -E graph
poetry install -E postgres -E kafka -E lakehouse

Optional dependency failures have three distinct causes:

  • A missing module means the extra is not installed. Add the matching Poetry extra.

  • A package that imports but lacks Producer, Schema, SchemaRegistryClient, or callable psycopg.connect is incomplete. Repair it with poetry install -E kafka -E postgres; FraudTwin reports this separately from a missing service.

  • A connection-refused or health-check failure means the client is installed but Kafka, Schema Registry, or PostgreSQL is unavailable.

The base installation remains valid for offline generation and tutorials. Verify both optional clients with:

poetry run python -c \
  "from confluent_kafka import Producer; from confluent_kafka.schema_registry import Schema, SchemaRegistryClient; print('Kafka extra OK')"

poetry run python -c \
  "import psycopg; assert callable(psycopg.connect); print('PostgreSQL extra OK')"

Configuration validation fails#

Run validation before generation and inspect the first reported field:

poetry run fraudtwin config validate configs/minimal.yaml

Unknown fields are rejected intentionally. Check required relationships such as accounts needing customers and institutions, rail weights summing to 1.0, and timezone-aware simulation timestamps.

Labels are missing or unresolved#

Check label_available_at against prediction_time. A label may be true in oracle data but unavailable operationally. Review dataset.unresolved_labels and the configured workflow/observation delay before changing model code.

Graph export is empty or incomplete#

Confirm that graph scenarios were enabled and that the selected view, as_of, from_time, and to_time lie inside the source run window. Observable exports intentionally omit future and latent oracle-only relationships.

Scale runs stop or cannot resume#

Use a bounded profile locally, keep the checkpoint directory intact, and resume from its manifest:

CONFIG=configs/scale-1b.yaml
CHECKPOINT_DIR=./runs/scale-checkpoint

fraudtwin generate "$CONFIG" --workers 16 --checkpoint-dir "$CHECKPOINT_DIR"
fraudtwin resume "$CHECKPOINT_DIR"

Resume validates the resolved configuration and seed tree. Do not edit a checkpoint or versioned benchmark fixture in place.

Next#

Return to the relevant learning path after the environment is healthy.