laravel/framework · error · RuntimeException

Vector distance queries are only supported by Postgres.

Error message

Vector distance queries are only supported by Postgres.

What it means

Thrown by Builder::ensureConnectionSupportsVectors() when orderByVectorDistance() is called on a connection that is not a PostgresConnection. Vector distance ordering compiles to the pgvector `<=>` operator which only exists on Postgres with the pgvector extension. Laravel refuses to emit it for other engines because the SQL would be rejected at the database level.

Source

Thrown at src/Illuminate/Database/Query/Builder.php:4779

     *
     * @return \Illuminate\Database\ConnectionInterface
     */
    public function getConnection()
    {
        return $this->connection;
    }

    /**
     * Ensure the database connection supports vector queries.
     *
     * @return void
     *
     * @throws \RuntimeException
     */
    protected function ensureConnectionSupportsVectors()
    {
        if (! $this->connection instanceof PostgresConnection) {
            throw new RuntimeException('Vector distance queries are only supported by Postgres.');
        }
    }

    /**
     * Get the database query processor instance.
     *
     * @return \Illuminate\Database\Query\Processors\Processor
     */
    public function getProcessor()
    {
        return $this->processor;
    }

    /**
     * Get the query grammar instance.
     *
     * @return \Illuminate\Database\Query\Grammars\Grammar
     */

View on GitHub (pinned to bd6b5437e6)

Solutions

Switch the DB connection to Postgres (config/database.php) and install the pgvector extension for the vector column type.
If you must support multiple engines, branch on $builder->getConnection()->getDriverName() === 'pgsql' before calling orderByVectorDistance.
For local/test parity, run tests against a Postgres (with pgvector) container instead of SQLite.

Example fix

// before
$posts = DB::table('documents')->orderByVectorDistance('embedding', $vec)->get();

// after (guard by driver)
$query = DB::table('documents');
if ($query->getConnection()->getDriverName() === 'pgsql') {
    $query->orderByVectorDistance('embedding', $vec);
}
$posts = $query->get();

Defensive patterns

Strategy: validation

Validate before calling

// Check before calling orderByVectorDistance
if ($builder->getConnection() instanceof \Illuminate\Database\PostgresConnection) {
    $builder->orderByVectorDistance('embedding', $vector);
} else {
    throw new \LogicException('Vector distance ordering requires a Postgres connection with pgvector.');
}

Type guard

function supportsVectorDistance(\Illuminate\Database\Query\Builder $query): bool
{
    return $query->getConnection() instanceof \Illuminate\Database\PostgresConnection;
}

Prevention

Centralise vector queries in a repository that asserts the Postgres driver.
Keep production and test databases both on Postgres+pgvector to avoid engine drift.
Document the pgvector requirement wherever orderByVectorDistance is used.

When it happens

Trigger: Calling orderByVectorDistance($column, $vector) (or passing a vector string) on a query builder whose underlying connection is MySQL, SQLite, or SQL Server. The check happens in ensureConnectionSupportsVectors() via `instanceof PostgresConnection` before any SQL is built.

Common situations: Developing AI/RAG features locally against SQLite or MySQL, then deploying the same code expecting Postgres. Forgetting to install/enable the pgvector extension on the Postgres connection also surfaces nearby failures. Running tests against an in-memory SQLite database that share query code with production Postgres.

Related errors

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/3d3a2a4c7b32f20c.json. Report an issue: GitHub.