appwrite/appwrite · error · InvalidArgumentException

bulkEmbed requires at least one text

Error message

bulkEmbed requires at least one text

What it means

Thrown by the Appwrite agents adapter's bulkEmbed when called with an empty texts array. The bulk embedding endpoint requires at least one input string; sending an empty batch would produce a pointless API call. Guard the caller: only invoke bulkEmbed when the array contains at least one non-empty string.

Solutions

  1. Guard the call site: only invoke bulkEmbed when count($texts) > 0
  2. Return early (e.g. empty vector list) when the input batch is empty
  3. Fix upstream filtering logic that empties the batch unexpectedly

Example fix

// before
$vectors = $adapter->bulkEmbed($texts);
// after
$vectors = $texts === [] ? [] : $adapter->bulkEmbed($texts);
Defensive patterns

Strategy: validation

Validate before calling

if (count($texts) === 0) {
    return []; // or skip the embedding step
}
$vectors = $adapter->bulkEmbed($texts);

Try / catch

try {
    $vectors = $adapter->bulkEmbed($texts);
} catch (\InvalidArgumentException $e) {
    $vectors = []; // empty batch
}

Prevention

When it happens

Trigger: Calling bulkEmbed([]) directly, or via embed()/batch pipelines when the input list was filtered down to nothing.

Common situations: Empty database result sets or empty user input passed into an embedding step; collecting texts with array_filter that removed everything.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors


AI-assisted analysis of appwrite/appwrite@7eab5f1970 (2026-09-23). Data as JSON: /api/errors/8fb1254fabe78953. Report an issue: GitHub.

Appendix: source

Thrown at packages/agents/src/Adapters/Appwrite.php:107

        ];
    }

    /**
     * Bulk embedding generation — sends multiple texts in a single request.
     *
     * @param  array<int, string>  $texts
     * @return array{
     *     embeddings: array<int, array<int, float>>,
     *     tokensProcessed: int|null,
     *     totalDuration: int|null
     * }
     *
     * @throws \Exception
     */
    public function bulkEmbed(array $texts): array
    {
        if (empty($texts)) {
            throw new \InvalidArgumentException('bulkEmbed requires at least one text');
        }

        $payload = [
            'model' => $this->model,
            'texts' => array_values($texts),
        ];
        $response = $this->post($this->getEndpoint(), $payload);
        $json = json_decode((string) $response->getBody(), true);

        if (! is_array($json)) {
            throw new \Exception('Invalid response format received from the API');
        }

        if (isset($json['error'])) {
            throw new \Exception(is_string($json['error']) ? $json['error'] : 'Unknown error', $response->getStatusCode());
        }

        if (! isset($json['embeddings']) || ! is_array($json['embeddings']) || count($json['embeddings']) !== count($texts)) {

View on GitHub (pinned to 7eab5f1970)