I recently had to troubleshoot a vector index creation problem on Oracle AI Database Free. To be totally honest upfront: the problem wasn’t Oracle – it was me. Here’s a short story about what happened and what I did to remedy the situation.

I typically use {docker,podman}-compose to start my demo environments, because it’s the easiest way to tie network, volumes, and other details together in a well-understood format. The Oracle AI Database Free image allows me to run scripts during its initialisation, which is super convenient to set up demo environments. In this particular case I wanted to demo the use of Vector Indices in APEX, but I ran into a slight problem on the way, before the system even got to the APEX installation.

Initialisation Scripts for Oracle’s Database Free container image

Here is the full story. It began when I started my database from this compose file:

services:
  oraclefree:
    image: ${ORACLE_FREE_IMAGE}
    ports:
      - ${DB_HOST_PORT:-1521}:1521
    volumes:
      - ora_db_vol26ai:/opt/oracle/oradata
      - ./init:/container-entrypoint-initdb.d
      - ./onnx:/opt/oracle/onnx
    networks:
      - ora_network
    healthcheck:
      test: ["CMD", "/opt/oracle/healthcheck.sh"]
      interval: 10s
      timeout: 5s
      retries: 10
    environment:
      ORACLE_PASSWORD: ${ORACLE_PASSWORD}
      APP_USER: EMILY
      APP_USER_PASSWORD: ${APP_USER_PASSWORD}
volumes:
  ora_db_vol26ai:
networks:
  ora_network:

The host’s init directory contains a script to be run when the database is first initialised. The onnx directory contains the Oracle-provided all_MiniLM_L12_v2 ONNX model.

$ ls -l init
-rw-r--r--@ 1 martin.b.bach  staff  2236 Sep 25 15:17 01_vector_test.sql
$ ls -l onnx
total 284160
-rw-rw-rw-@ 1 martin.b.bach  staff  133322334 Oct 30  2025 all_MiniLM_L12_v2.onnx

The initialisation script loads the ONNX file into the database and creates an embedding model. This is used to generate vector embeddings from text. It then proceeds to create a table, add a vector column, and create vector embeddings for each fact. The important part is shown here. The table and its contents have been borrowed from Connor McDonald. By the way, you should have a look at his GitHub, there is a lot of cool stuff about Oracle AI Database 26ai to be found.

alter session set container = freepdb1;
-- more initialisation code
alter session set current_schema = EMILY;
create table trivia (
    pk int generated as identity,
    facts varchar2(256),
    vec vector
);
insert into trivia (facts) values 
(q'{Dogs have about 1,700 taste buds.}'),
(q'{A dog's sense of smell is 40 times better than humans.}'),
(q'{Dogs sweat through their paws.}'),
(q'{The Basenji dog doesn't bark.}'),
(q'{Puppies are born deaf.}'),
(q'{Dogs can understand up to 250 words and gestures.}'),
(q'{Dogs have three eyelids.}'),
(q'{A dog's nose print is unique.}'),
(q'{Dogs can be trained to detect diseases.}'),
(q'{The Chihuahua is the smallest dog breed.}'),
(q'{Greyhounds can run up to 45 mph.}'),
(q'{A dog's sense of hearing is four times better than humans.}'),
(q'{Dogs dream similarly to humans.}'),
(q'{Labradors are the most popular breed.}'),
(q'{Dogs have twice as many muscles for moving their ears as humans.}'),
(q'{The Newfoundland breed has webbed feet.}'),
(q'{Dalmatian puppies are born completely white.}'),
(q'{Dogs have an excellent sense of time.}'),
(q'{The Basenji is known as the "barkless dog."}'),
(q'{Dogs curl up to protect their organs.}');
update
  trivia
set
  vec = vector_embedding(ALL_MINILM_L12_V2 using facts as data);
create vector index facts_idx on trivia(vec)
organization inmemory neighbor graph
distance cosine
with target accuracy 95;

So far, so good. However, during the bootstrap sequence, something went wrong.

Error creating the vector index

The last statement, intended to create the vector index, fails with an error:

oraclefree-1  | create vector index facts_idx on trivia(vec)
oraclefree-1  |                                  *
oraclefree-1  | ERROR at line 1:
oraclefree-1  | ORA-51962: The vector memory area is out of space for the current container.
oraclefree-1  | Help: https://docs.oracle.com/error-help/db/ora-51962/

Which is, again, not Oracle’s fault. The documentation clearly states that a vector pool must be configured first, before vector indices can be created.

The fix

The fix described here is specific to the Oracle AI Database Free container image and its RPM cousins. Database Free has a strict memory limit of 2GB, and although vector_memory_size is a dynamic init.ora parameter I had more success setting it at SPFILE level and bouncing the database than trying to reallocate memory.

I was unsure at first if bouncing the instance during container initialisation would work without introducing additional problems. It turned out to be dead simple: the init directory gets a new addition, 00_vector_area.sql, which contains just 2 lines. Because this script runs as SYS in CDB$ROOT, it sets the CDB-level Vector Pool size to 128 MB. PDB-level Vector Pool limits are a separate consideration but they don’t apply to my demo.

-- this script runs as SYS in CDB$ROOT
alter system set VECTOR_MEMORY_SIZE = 128M scope = spfile;
startup force

That’s it! Now that the vector pool size is greater than 0 after the database restarted, the index is successfully created, and my demo is saved 🙏

oraclefree-1  | 20 rows created.
oraclefree-1  | 
oraclefree-1  | 
oraclefree-1  | 20 rows updated.
oraclefree-1  | 
oraclefree-1  | 
oraclefree-1  | Index created.

I should probably add that any script in container-entrypoint-initdb.d is executed only once, during testing I tore the entire compose environment down and started it up to ensure everything works as expected.

Summary

Remember to allocate space for the Vector area, or else you might run into problems creating those Inverted File Flat (IVF) and Hierarchical Navigable Small World (HNSW) index types.