# Troubleshooting Common Development Issues in OpenMetadata: A Complete Technical Guide

> Troubleshoot common OpenMetadata development issues with this technical guide. Learn to fix environment misconfigs, schema gaps, and registry problems to save debugging time.

- Repository: [OpenMetadata/OpenMetadata](https://github.com/open-metadata/OpenMetadata)
- Tags: how-to-guide
- Published: 2026-04-23

---

**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`](https://github.com/open-metadata/OpenMetadata/blob/main/DEVELOPER.md) — "Preferred Workflow by Language" (line 31)

**Quick fix:**

```bash
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:

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-service/pom.xml) (root of backend)

**Quick fix:**

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

```

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

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-ui/src/main/resources/ui/src/index.tsx)

**Quick fix:**

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/DEVELOPER.md) (line 56)

**Quick fix:**

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

2. Run generation commands:

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/bootstrap/sql/MIGRATION_SYSTEM.md)

**Quick fix:**

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

```bash
make run_local_docker  # Spins up clean DB with migrations applied

```

Or manually verify with Docker:

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

```

Check `SERVER_CHANGE_LOG` in [`MIGRATION_SYSTEM.md`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-service/src/main/java/org/openmetadata/service/Entity.java) (line 86)

**Quick fix:**

Add the constant and register the DAO:

```java
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`](https://github.com/open-metadata/OpenMetadata/blob/main/EntityResource.java) (line 111)

**Quick fix:**

Verify the subclass:
- Overrides `FIELDS` correctly
- Uses `@Path("/v1/myEntities")` annotation

```java
@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`](https://github.com/open-metadata/OpenMetadata/blob/main/ingestion/src/metadata/ingestion/source/database/postgres/source.py) and `TopologyRunnerMixin`

**Quick fix:**

1. Verify [`connection.py`](https://github.com/open-metadata/OpenMetadata/blob/main/connection.py) has correct authentication
2. Ensure `TopologyNode` producers return iterators:

```python
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:

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

```

Always run linting before testing:

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/BaseEntityIT.java) in `openmetadata-integration-tests`

**Quick fix:**

Isolate unit tests:

```bash
mvn test -DskipITs

```

Or use deterministic Docker setup:

```bash
./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`](https://github.com/open-metadata/OpenMetadata/blob/main/TableIndex.java))

**Quick fix:**

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

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/Entity.java) (line 86) with constants and DAO registration
- **Python ingestion** follows topology patterns — verify [`connection.py`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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.