apache/seatunnel · error · TypesenseConnectorException

QUERY_COLLECTION_LIST_ERROR

QUERY_COLLECTION_LIST_ERROR

Error message

QUERY_COLLECTION_LIST_ERROR.getDescription()

What it means

TypesenseClient.collectionList() fetches the list of collections from the Typesense server; any failure in that API call is converted to TypesenseConnectorException with the QUERY_COLLECTION_LIST_ERROR code, hiding the root cause.

Solutions

1. Test the /collections endpoint manually with the configured URL and API key
2. Confirm the typesense-java client version matches the server's API version
3. Check auth: the key must have permission to list collections
4. Rethrow with the cause attached to surface the actual API error

Example fix

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

// sanity-check configuration before calling
if (typesenseUrl == null || typesenseApiKey == null) {
    throw new IllegalArgumentException("Typesense URL/API key must be configured");
}

try {
    list = client.collectionList();
} catch (TypesenseConnectorException e) {
    // exponential backoff retry; abort after N attempts with cause context
}

When it happens

Trigger: Calling collectionList() (e.g. during catalog table discovery) when the /collections endpoint returns an error: invalid API key, unreachable server, 5xx from Typesense, or malformed response deserialization.

Common situations: Catalog operations listing Typesense collections with wrong credentials; Typesense version upgrade changing the API response shape; proxy/firewall blocking the request.

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_EXISTS_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/ca8e213d264d7dff. 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:168

            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(
                    QUERY_COLLECTION_LIST_ERROR, QUERY_COLLECTION_LIST_ERROR.getDescription());
        }
    }

    public Map<String, String> getField(String collection) {
        if (collectionExists(collection)) {
            Map<String, String> fieldMap = new HashMap<>();
            try {
                CollectionResponse collectionResponse = tsClient.collections(collection).retrieve();
                List<Field> fields = collectionResponse.getFields();
                for (Field field : fields) {
                    String fieldName = field.getName();
                    String type = field.getType();
                    fieldMap.put(fieldName, type);
                }
            } catch (Exception e) {
                log.error(FIELD_TYPE_MAPPING_ERROR.getDescription());
                throw new TypesenseConnectorException(

View on GitHub (pinned to cf67b549a7)