{"record":{"id":"7763af5f66097b11","repo":"apache/seatunnel","slug":"insert-doc-error-7763af","errorCode":"INSERT_DOC_ERROR","errorMessage":"INSERT_DOC_ERROR.getDescription()","messagePattern":"INSERT_DOC_ERROR\\.getDescription\\(\\)","errorType":"error_code","errorClass":"TypesenseConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-typesense/src/main/java/org/apache/seatunnel/connectors/seatunnel/typesense/sink/TypesenseSinkWriter.java","lineNumber":127,"sourceCode":"\n    @Override\n    public Optional<TypesenseCommitInfo> prepareCommit() {\n        insert(this.collection, this.requestEsList);\n        return Optional.empty();\n    }\n\n    private void insert(String collection, List<String> requestEsList) {\n        try {\n            RetryUtils.retryWithException(\n                    () -> {\n                        typesenseClient.insert(collection, requestEsList);\n                        return null;\n                    },\n                    retryMaterial);\n            requestEsList.clear();\n        } catch (Exception e) {\n            log.error(INSERT_DOC_ERROR.getDescription());\n            throw new TypesenseConnectorException(\n                    INSERT_DOC_ERROR, INSERT_DOC_ERROR.getDescription());\n        }\n    }\n\n    @Override\n    public void abortPrepare() {}\n\n    @Override\n    public void close() {\n        insert(collection, requestEsList);\n    }\n}\n","sourceCodeStart":109,"sourceCodeEnd":140,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-typesense/src/main/java/org/apache/seatunnel/connectors/seatunnel/typesense/sink/TypesenseSinkWriter.java#L109-L140","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the log before this exception for the underlying cause and verify Typesense server health/connectivity.","Validate that all fields written exist in the Typesense collection schema and have compatible types.","Verify the API key has document write permissions on the target collection.","Tune retry configuration (attempts/backoff) to absorb transient failures; re-run the job — the batch is retried from checkpoint state."],"exampleFix":"// before\ncatch (Exception e) {\n    log.error(INSERT_DOC_ERROR.getDescription());\n    throw new TypesenseConnectorException(INSERT_DOC_ERROR, INSERT_DOC_ERROR.getDescription());\n}\n// after\ncatch (Exception e) {\n    log.error(\"insert docs failed, collection={}, batchSize={}\", collection, requestEsList.size(), e);\n    throw new TypesenseConnectorException(INSERT_DOC_ERROR, INSERT_DOC_ERROR.getDescription(), e);\n}","handlingStrategy":"retry","validationCode":"// pre-flight: collection writable and reachable\nCollection col = client.collections(collection).retrieve(); // throws early if missing/no auth","typeGuard":null,"tryCatchPattern":"try {\n    writer.insert(serializedBatch);\n} catch (TypesenseConnectorException e) {\n    if (e.getErrorCode() == INSERT_DOC_ERROR) {\n        // rely on checkpoint restart or manually re-submit the batch\n    }\n}","preventionTips":["Verify the Typesense collection schema contains all fields being written.","Confirm API key write permissions before running the job.","Tune retry attempts/backoff to tolerate transient network issues; keep batches small."],"tags":["typesense","sink","http","batch-write","retry"],"backgroundTag":"database-write-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}