apache/seatunnel · error · TypesenseConnectorException

QUERY_COLLECTION_EXISTS_ERROR

QUERY_COLLECTION_EXISTS_ERROR

Error message

QUERY_COLLECTION_EXISTS_ERROR.getDescription()

What it means

TypesenseClient.collectionExists() lists all collections and matches by name; any exception from the Typesense API (connectivity, auth, server error) is caught and rethrown as TypesenseConnectorException with QUERY_COLLECTION_EXISTS_ERROR. The underlying cause is discarded.

Solutions

1. Verify Typesense URL and API key in the connector configuration and test with curl /collections
2. Check Typesense server health/logs and network reachability from the SeaTunnel worker
3. Chain the original exception when rethrowing so the real failure is visible
4. Retry the existence check after transient failures (connection resets, leader election in the Typesense cluster)

Example fix

// before
} catch (Exception e) {
    log.error(QUERY_COLLECTION_EXISTS_ERROR.getDescription());
    throw new TypesenseConnectorException(QUERY_COLLECTION_EXISTS_ERROR, QUERY_COLLECTION_EXISTS_ERROR.getDescription());
}
// after
} catch (Exception e) {
    log.error(QUERY_COLLECTION_EXISTS_ERROR.getDescription(), e);
    throw new TypesenseConnectorException(QUERY_COLLECTION_EXISTS_ERROR, QUERY_COLLECTION_EXISTS_ERROR.getDescription(), e);
}

// pre-check connectivity/credentials with a lightweight call
HttpResponse<String> resp = httpClient.send(requestTo(typesenseUrl + "/collections"), BodyHandlers.ofString());
boolean apiReachable = resp.statusCode() == 200;

try {
    exists = client.collectionExists(collection);
} catch (TypesenseConnectorException e) {
    // treat as indeterminate; check URL/API key and retry with backoff
}

When it happens

Trigger: Calling collectionExists (directly or via getField/createCollection) while the Typesense endpoint is down, the API key is invalid, or the retrieve-collections API call fails.

Common situations: Misconfigured TypesenseUrl/TypesenseApiKey in the SeaTunnel config; Typesense cluster restart or TLS mismatch; collection name checks during schema auto-creation in a catalog.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• DROP_COLLECTION_ERROR
• QUERY_COLLECTION_LIST_ERROR
• Airtable API request failed, status code
• COMMON-02
• CREATE_COLLECTION_ERROR

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/7985a512d3a245a2. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-typesense/src/main/java/org/apache/seatunnel/connectors/seatunnel/typesense/client/TypesenseClient.java:150

        searchParameters.perPage(pageSize);
        SearchResult searchResult =
                tsClient.collections(collection).documents().search(searchParameters);
        return searchResult;
    }

    public boolean collectionExists(String collection) {
        try {
            Collections collections = tsClient.collections();
            CollectionResponse[] collectionResponses = collections.retrieve();
            for (CollectionResponse collectionRespons : collectionResponses) {
                String collectionName = collectionRespons.getName();
                if (collection.equals(collectionName)) {
                    return true;
                }
            }
        } catch (Exception e) {
            log.error(QUERY_COLLECTION_EXISTS_ERROR.getDescription());
            throw new TypesenseConnectorException(
                    QUERY_COLLECTION_EXISTS_ERROR, QUERY_COLLECTION_EXISTS_ERROR.getDescription());
        }
        return false;
    }

    public List<String> collectionList() {
        try {
            Collections collections = tsClient.collections();
            CollectionResponse[] collectionResponses = collections.retrieve();
            List<String> list = new ArrayList<>();
            for (CollectionResponse collectionRespons : collectionResponses) {
                String collectionName = collectionRespons.getName();
                list.add(collectionName);
            }
            return list;
        } catch (Exception e) {
            log.error(QUERY_COLLECTION_LIST_ERROR.getDescription());
            throw new TypesenseConnectorException(

View on GitHub (pinned to cf67b549a7)