apache/seatunnel · error · TypesenseConnectorException

QUERY_COLLECTION_NUM_ERROR

QUERY_COLLECTION_NUM_ERROR

Error message

QUERY_COLLECTION_NUM_ERROR.getDescription()

What it means

collectionDocNum counts documents in a Typesense collection by issuing a wildcard search (q=*) and returning SearchResult.getFound(). If the search call throws (unreachable server, nonexistent collection, bad API key, malformed query), the client wraps it in TypesenseConnectorException with QUERY_COLLECTION_NUM_ERROR.

Solutions

1. Verify collection name and API key (key must have documents:search permission on the target collection).
2. Confirm Typesense reachability with a direct REST call, e.g. GET /collections/<name> (also returns num_documents without a search).
3. If only a count is needed, use the collection metadata endpoint instead of a wildcard search.
4. Capture/log the underlying exception to see the real HTTP status before retrying.

Example fix

// before
} catch (Exception e) {
    log.error(QUERY_COLLECTION_NUM_ERROR.getDescription());
    throw new TypesenseConnectorException(QUERY_COLLECTION_NUM_ERROR, QUERY_COLLECTION_NUM_ERROR.getDescription());
}
// after
} catch (Exception e) {
    log.error("query collection doc num failed, collection={}", collection, e);
    throw new TypesenseConnectorException(QUERY_COLLECTION_NUM_ERROR, QUERY_COLLECTION_NUM_ERROR.getDescription(), e);
}

// verify collection is reachable before counting
CollectionsResponse cols = client.collections().get();
boolean exists = cols.stream().anyMatch(c -> c.getName().equals(collection));

try {
    long n = client.collectionDocNum(collection);
} catch (TypesenseConnectorException e) {
    if (e.getErrorCode() == QUERY_COLLECTION_NUM_ERROR) { /* check auth/connectivity, retry */ }
}

When it happens

Trigger: typesenseClient.collectionDocNum(collection) performs tsClient.collections(collection).documents().search(q) and the server returns an error or the request fails at the network level. Typically called during sink/source initialization to size or validate the collection.

Common situations: Collection name typo in configuration; Typesense API key lacking search permission; Typesense node down or wrong port; version mismatch where the search endpoint path differs.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• DELETE_COLLECTION_ERROR
• Failed to drop table
• INSERT_DOC_ERROR
• ADD_FIELD_FAILED
• Airtable API request failed, status code

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/af9735c41aa5cab2. 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:284

    public boolean deleteCollectionData(String collection, String id) {
        try {
            tsClient.collections(collection).documents(id).delete();
        } catch (Exception e) {
            log.error(DELETE_COLLECTION_ERROR.getDescription());
            throw new TypesenseConnectorException(
                    DELETE_COLLECTION_ERROR, DELETE_COLLECTION_ERROR.getDescription());
        }
        return true;
    }

    public long collectionDocNum(String collection) {
        SearchParameters q = new SearchParameters().q("*");
        try {
            SearchResult searchResult = tsClient.collections(collection).documents().search(q);
            return searchResult.getFound();
        } catch (Exception e) {
            log.error(QUERY_COLLECTION_NUM_ERROR.getDescription());
            throw new TypesenseConnectorException(
                    QUERY_COLLECTION_NUM_ERROR, QUERY_COLLECTION_NUM_ERROR.getDescription());
        }
    }
}

View on GitHub (pinned to cf67b549a7)