apache/seatunnel · error · TypesenseConnectorException

INSERT_DOC_ERROR

INSERT_DOC_ERROR

Error message

INSERT_DOC_ERROR.getDescription()

What it means

TypesenseSinkWriter.insert batches serialized documents and flushes them to Typesense with retry via a retryable async call. If the flush attempt ultimately fails (retries exhausted or non-retryable failure), it logs INSERT_DOC_ERROR and throws TypesenseConnectorException(INSERT_DOC_ERROR) — the original cause is discarded from the thrown exception.

Source

Thrown at seatunnel-connectors-v2/connector-typesense/src/main/java/org/apache/seatunnel/connectors/seatunnel/typesense/sink/TypesenseSinkWriter.java:127

    @Override
    public Optional<TypesenseCommitInfo> prepareCommit() {
        insert(this.collection, this.requestEsList);
        return Optional.empty();
    }

    private void insert(String collection, List<String> requestEsList) {
        try {
            RetryUtils.retryWithException(
                    () -> {
                        typesenseClient.insert(collection, requestEsList);
                        return null;
                    },
                    retryMaterial);
            requestEsList.clear();
        } catch (Exception e) {
            log.error(INSERT_DOC_ERROR.getDescription());
            throw new TypesenseConnectorException(
                    INSERT_DOC_ERROR, INSERT_DOC_ERROR.getDescription());
        }
    }

    @Override
    public void abortPrepare() {}

    @Override
    public void close() {
        insert(collection, requestEsList);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the log before this exception for the underlying cause and verify Typesense server health/connectivity.
2. Validate that all fields written exist in the Typesense collection schema and have compatible types.
3. Verify the API key has document write permissions on the target collection.
4. Tune retry configuration (attempts/backoff) to absorb transient failures; re-run the job — the batch is retried from checkpoint state.

Example fix

// before
catch (Exception e) {
    log.error(INSERT_DOC_ERROR.getDescription());
    throw new TypesenseConnectorException(INSERT_DOC_ERROR, INSERT_DOC_ERROR.getDescription());
}
// after
catch (Exception e) {
    log.error("insert docs failed, collection={}, batchSize={}", collection, requestEsList.size(), e);
    throw new TypesenseConnectorException(INSERT_DOC_ERROR, INSERT_DOC_ERROR.getDescription(), e);
}

// pre-flight: collection writable and reachable
Collection col = client.collections(collection).retrieve(); // throws early if missing/no auth

try {
    writer.insert(serializedBatch);
} catch (TypesenseConnectorException e) {
    if (e.getErrorCode() == INSERT_DOC_ERROR) {
        // rely on checkpoint restart or manually re-submit the batch
    }
}

When it happens

Trigger: The retryable supplier executing the batch insert into Typesense throws: server unreachable, batch rejected by Typesense (schema/field mismatch), API key lacking write permission, or retry budget (retryMaterial) exhausted.

Common situations: Typesense collection schema missing a field present in the documents; network instability exceeding the retry policy; wrong API key/permissions; oversized batch; Typesense node restart during write.

Related errors

• Failed to execute HTTP request to %s after %d attempts
• Failed to flush data in prepareCommit
• FLUSH_DATA_FAILED
• FLUSH_DATA_FAILED
• Failed to drop table %s in catalog %s

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