apache / apache/seatunnel

[Bug][CLI] Connector knowledge base degrades silently without metadata; not-found suggestions can echo the queried name

Open
#11,650 3 comments 0 reactions 1 assignee Claimed by @SEZ9 View on GitHub
bug
Dominant language
Java
Stars
9.7k
Forks
2.4k
Avg merge
3d 9h
Merged PRs (30d)
204

Description

### Search before asking

- [X] I had searched in the [issues](https://github.com/apache/seatunnel/issues?q=is%3Aissue) and found no similar issues.

### What happened

Sub-task of #11616 (Stage-1 items 1.1-context and 1.6). Two related defects in the CLI's connector knowledge base, both observed during the accuracy benchmark (#11553) and partially responsible for the "all models fail on Doris/StarRocks" clusters:

**1. Silent degradation to zero connector knowledge in source checkouts / pip installs.**

`connector_metadata.json` is generated by Java reflection during the seatunnel-dist build and only exists in the release tarball layout. In a source checkout or pip install without `SEATUNNEL_HOME`, `_load_runtime_metadata()` silently returns empty (a `logger.debug`), and:
- the system-prompt catalog renders as `## Available Connectors (0 connectors, 0 endpoints)` — the model is told there are no connectors at all;
- `validate_connector_options` returns `valid: True` for everything ("metadata not available"), so generated configs are unchecked;
- `get_connector_detail("Doris")` falls through to "not found".

**2. The not-found suggester can echo the queried name back.**

`get_connector_detail` uses `route_by_keyword(name)` (keyword routing, not name correction) for suggestions, producing the absurd `Connector 'Doris' not found. Did you mean: Doris?` — because "doris" is its own keyword alias. There is also no fuzzy correction for invented names: benchmark runs observed a model writing `File` (a non-existent connector) for LocalFile, and the error gave no usable hint, so the repair loop could not recover.

### What you expected to happen

- A valid connector name without available metadata should be told "known connector, option metadata unavailable (+ remediation hint)" instead of "not found".
- Unknown names should get edit-distance/substring suggestions ("File" → LocalFile, FtpFile, S3File...) that never include the queried name itself.
- The catalog should never claim "0 connectors" when a static name index exists; it should list known names and state clearly that option details are unavailable.
- The degradation should be visible (warning log), not silent.

### SeaTunnel Version

dev

### SeaTunnel Config

n/a (CLI behavior)

### Running Command

```
# any source checkout without SEATUNNEL_HOME / metadata file
seatunnel "sync PostgreSQL orders to Doris"
```

### Error Exception

See above ("Did you mean: Doris?").

### Zeta or Flink or Spark Version

_No response_

### Java or Scala Version

Python 3.10+ (seatunnel-cli)

### Screenshots

_No response_

### Are you willing to submit PR?

- [X] Yes I am willing to submit a PR!

### Code of Conduct

- [X] I agree to follow this project's [Code of Conduct](https://www.apache.org/foundation/policies/conduct)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.