systematic-debugging

Systematic Debugging for OpenMetadata

Structured 4-phase debugging process. Stops you from guessing and forces root cause identification.

When to Use

• Test failures with unclear cause
• Build errors after dependency or schema changes
• Runtime exceptions in backend, frontend, or ingestion
• Issues that persist after 2+ fix attempts

Phase 1: Gather Evidence

Do not change any code yet. Only observe and collect data.

1. Read the full error — not just the last line. Stack traces, build logs, test output.
2. Reproduce reliably:

   # Java
   mvn test -pl <module> -Dtest=FailingTest#failingMethod
   
   # Python
   source env/bin/activate && cd ingestion
   python -m pytest tests/unit/path/to/test.py::test_name -v
   
   # TypeScript
   cd openmetadata-ui/src/main/resources/ui
   yarn test path/to/test.spec.ts
   
   # E2E
   yarn playwright:run --grep "test name"
   

3. Check what changed recently:

   git log --oneline -20
   git diff HEAD~5 -- <relevant-directory>
   

4. Document findings: Write down the exact error, when it started, and what you've observed.

Phase 2: Form Hypotheses

Based on the evidence, list 2-3 possible causes ranked by likelihood:

1. [Most likely] Schema change in X broke generated model Y
   Evidence: error mentions field Z, git log shows schema modified 3 commits ago
2. [Possible] Dependency version mismatch after recent upgrade
   Evidence: ClassNotFoundException for new API
3. [Unlikely] Test environment state pollution
   Evidence: test passes in isolation but fails in suite

Do not jump to fixing yet. Verify the top hypothesis first.

Phase 3: Verify Root Cause

Test your top hypothesis with the smallest possible experiment:

• Read the suspected code — don't guess what it does
• Add targeted logging or use a debugger if needed
• Check one hypothesis at a time — don't make multiple changes simultaneously

Common OpenMetadata Root Causes

Symptom	Likely Cause	Verification
ImportError in Python	Models not regenerated after schema change	make generate then retry
TypeScript compile error on generated types	Schema changed, types not rebuilt	yarn parse-schema then retry
Java NullPointerException in entity	Missing field in Flyway migration	Check bootstrap/sql/migrations/
Test passes alone, fails in suite	Shared state mutation between tests	Run with --forked (Java) or -x (pytest)
404 Not Found on API endpoint	Missing @Path annotation or route config	Check resource class registration
UI component renders blank	Missing i18n key	Check locale/languages/en-us.json
Connection refused in integration test	Docker service not running	docker compose -f docker/development/docker-compose.yml ps