Troubleshooting Common Development Issues in OpenMetadata: A Complete Technical Guide

Most OpenMetadata development issues stem from environment misconfiguration, schema-to-code generation gaps, or missing entity registry steps — understanding the repository's architecture prevents hours of debugging.

OpenMetadata is a large, multi-module project spanning Java services, a React-TypeScript UI, and a Python ingestion framework. Because the codebase follows a schema-first, topology-driven architecture, many problems trace back to a handful of core concepts. This guide covers the most frequent pain points developers encounter and shows exactly where the relevant logic lives in the open-metadata/OpenMetadata repository.

---

Environment Setup Issues

Missing Prerequisites or Environment Variables

The most common blocker for new contributors is incomplete environment configuration. Symptoms include java -version or python not found, or Maven builds failing with cryptic path errors.

Where to look: DEVELOPER.md — "Preferred Workflow by Language" (line 31)

Quick fix:

make prerequisites

This installs JDK 21, Node 20, Python 3.11+, and verifies JAVA_HOME and PYTHONPATH are set. If make is unavailable, manually install these versions and export the environment variables:

export JAVA_HOME=/path/to/jdk-21
export PYTHONPATH=/path/to/OpenMetadata/ingestion

---

Build and Compilation Failures

Maven Build Failures

When mvn clean install stops at a module or throws NoClassDefFoundError, the issue typically stems from corrupted local dependencies or skipped code generation.

Where to look: openmetadata-service/pom.xml (root of backend)

Quick fix:

mvn dependency:purge-local-repository
mvn clean install -DskipTests

The -DskipTests flag is essential during iterative development. Run tests separately when needed:

mvn test -Dtest=SpecificTestClass

Yarn and UI Compilation Errors

TypeScript errors like "Module not found" or "cannot find name 't'" indicate missing generated types or stale dependencies.

Where to look: UI entry point openmetadata-ui/src/main/resources/ui/src/index.tsx

Quick fix:

cd openmetadata-ui/src/main/resources/ui
yarn install && yarn lint:fix
yarn parse-schema  # Critical: generates TypeScript types from JSON schemas

yarn start

The UI depends on generated types from schemas. Always run yarn parse-schema after schema changes.

---

Schema-First Generation Issues

Missing Generated Code After Schema Edits

When POJOs, TypeScript interfaces, or Python models don't appear after editing a schema, the generation pipeline wasn't triggered correctly.

Where to look: Generation scripts referenced in DEVELOPER.md (line 56)

Quick fix:

1. Edit JSON schema in openmetadata-spec/src/main/resources/json/schema/...

2. Run generation commands:

make generate  # Python models & TS types

mvn clean install -pl openmetadata-spec  # Java POJOs

3. Verify output:
   • Java: openmetadata-service/target/generated-sources/
   • Python: ingestion/src/metadata/generated/
   • TypeScript: openmetadata-ui/src/main/resources/ui/src/generated/

---

Database Migration Problems

Flyway Migration Errors

Errors like "Versioned migration missing" or "Column already exists" indicate incomplete migration scripts or version conflicts.

Where to look: Migration directory bootstrap/sql/migrations/native/ and bootstrap/sql/MIGRATION_SYSTEM.md

Quick fix:

Ensure both MySQL and PostgreSQL scripts exist for every migration. For a fresh start:

make run_local_docker  # Spins up clean DB with migrations applied

Or manually verify with Docker:

./docker/run_local_docker.sh -m no-ui -d mysql

Check SERVER_CHANGE_LOG in MIGRATION_SYSTEM.md for version tracking.

---

Entity Registration and REST Resource Issues

"Entity Type Not Found" Errors

When adding a new entity, this error means the constant wasn't registered in the central registry.

Where to look: openmetadata-service/src/main/java/org/openmetadata/service/Entity.java (line 86)

Quick fix:

Add the constant and register the DAO:

public static final String MY_ENTITY = "myEntity";
// In initialization or constructor:
register(MY_ENTITY, MyEntity.class, new MyEntityRepository());

404 Errors or Missing Fields in REST Responses

REST endpoint issues trace back to incorrect path annotations or missing field definitions.

Where to look: EntityResource.java (line 111)

Quick fix:

Verify the subclass:

• Overrides FIELDS correctly
• Uses @Path("/v1/myEntities") annotation

@Path("/v1/myEntities")
public class MyEntityResource extends EntityResource<MyEntity, MyEntityRepository> {
    public static final String FIELDS = "owner,tags,extension";
    // ...
}

---

Python Ingestion Failures

"SourceHash Mismatch" or "No Data Yielded"

These errors indicate topology configuration problems or authentication failures.

Where to look: Connector topology in ingestion/src/metadata/ingestion/source/database/postgres/source.py and TopologyRunnerMixin

Quick fix:

1. Verify connection.py has correct authentication
2. Ensure TopologyNode producers return iterators:

from metadata.ingestion.source.database.postgres.source import PostgresSource
from metadata.ingestion.models.topology import TopologyRunnerMixin

class DebugPostgresSource(PostgresSource, TopologyRunnerMixin):
    def get_services(self):
        print("Fetching services…")
        return super().get_services()

Run with:

python -m metadata.ingestion.run metadata ingest -c my_postgres.yaml

Always run linting before testing:

make lint && make py_format

---

Testing Flakiness

Intermittent Integration Test Failures

Integration tests (*IT.java) can fail unpredictably due to shared database state.

Where to look: BaseEntityIT.java in openmetadata-integration-tests

Quick fix:

Isolate unit tests:

mvn test -DskipITs

Or use deterministic Docker setup:

./docker/run_local_docker.sh -m no-ui -d mysql

---

Search Index Problems

Entities Not Appearing in UI Search

Missing search results indicate indexing issues or disabled search support.

Where to look: Index classes under openmetadata-service/src/main/java/org/openmetadata/service/search/indexes/ (e.g., TableIndex.java)

Quick fix:

1. Ensure supportsSearch = true in the repository constructor
2. Trigger re-index via API:

curl -X POST "http://localhost:8585/api/v1/search/reindex?entity=table" \
  -H "Authorization: Bearer $OM_TOKEN"

---

Summary

• Environment setup failures trace to missing prerequisites — use make prerequisites and verify JAVA_HOME/PYTHONPATH
• Build failures in Maven or Yarn usually need dependency cleanup and generated type refresh
• Schema-first generation requires running both make generate and mvn clean install -pl openmetadata-spec
• Database migrations need both MySQL and PostgreSQL scripts; use make run_local_docker for clean state
• Entity registration starts in Entity.java (line 86) with constants and DAO registration
• Python ingestion follows topology patterns — verify connection.py auth and iterator returns
• Search indexing requires supportsSearch = true and explicit re-index API calls

---

Frequently Asked Questions

How do I fix "cannot find symbol" errors after editing a JSON schema?

Run the full generation cycle: make generate for Python/TypeScript types, then mvn clean install -pl openmetadata-spec for Java POJOs. Verify output directories contain newly generated files before building downstream modules.

Why does my new entity return 404 despite adding the REST resource class?

Check three locations: Entity.java (line 86) for the constant definition, CollectionDAO for DAO registration, and your resource class for the @Path annotation. All three must be present for the endpoint to register with Jersey.

How do I debug Python connectors that yield no data?

Enable debug logging in your YAML config, then verify connection.py authentication succeeds. Check that your TopologyNode producer methods return iterators (not lists or None). Use TopologyRunnerMixin to trace execution flow through the graph.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}