Install AI Agent Skills  View Python SDK

Troubleshoot Autonomous AI Database Free Container Setup

Use the Autonomous AI Database Free Container page to perform the setup in order. Use this page after a command fails or the running container does not expose the expected ORDS endpoint. The configuration details explain the resource and service choices behind the checks below.

The examples use the container name adb-free and named volume OracleDBData. Use the Docker or Podman tab for container commands. Podman machine diagnostics apply to Podman on macOS and Windows.

Find the right section

If you need to… Go to
check a failed command or unknown symptom Collect basic diagnostics
troubleshoot Podman, Docker, ports, or resource issues Podman and container runtime
resolve a Database Actions timeout or sign-in failure Database Actions access
troubleshoot database startup, ORDS, or database permissions Database startup, ORDS, and permissions
understand ORDS pool settings and sizing ORDS pool configuration details
troubleshoot ORDS session pressure ORDS uses too many database sessions
troubleshoot a REST request, TLS, or authentication REST endpoint, TLS, and authentication
troubleshoot image pulls, proxies, or model downloads Registry, proxy, and Object Storage access
discard and recreate the local database Reset and recovery

Start with diagnostics

Begin with these read-only checks before changing container or database state.

Collect basic diagnostics

Check the container state and recent logs for your runtime:

docker ps -a --filter name=adb-free
docker logs --tail 200 adb-free
podman ps -a --filter name=adb-free
podman logs --tail 200 adb-free

For Podman on macOS or Windows, also check the virtual machine:

podman machine list
podman machine inspect
podman system df

Do not delete the database volume while diagnosing. It contains the database, users, wallet, and ORDS-managed state.

Podman and container runtime

Use these steps for VM startup, published ports, container state, and resource issues.

The Podman machine already exists

If podman machine init reports that the machine already exists, do not initialize another machine. Start the existing machine:

podman machine start

After starting the machine, run podman info and continue only when it returns host and runtime information. If that check fails, use Podman machine troubleshooting. If the machine is ready but lacks memory or disk for the selected workload, stop it and adjust the machine using the values described in resource sizing. Changing machine resources does not change the ADB-Free database’s internal storage or session limits.

Podman machine starts but its API is unavailable

Do not create the database volume or start the ADB-Free container until podman info succeeds. Inspect the machine state and startup log:

podman machine inspect podman-machine-default
podman machine list

If podman info reports ssh: handshake failed or connection reset by peer, inspect the saved Podman connection:

podman system connection list

The default connection should name the intended machine and its SSH port and identity should match podman machine inspect. If podman machine list shows LastUp: Never or inspect reports State: stopped, the VM is not available even if podman machine start printed a success message. Preserve the machine disk and do not create the database volume or ADB-Free container until podman info succeeds. A guest log can show ready.service or multi-user.target after an earlier Ignition failure, so check the matching Ignition messages as well as the final boot lines. If podman info still resets and the saved connection matches, this is a Podman VM/host transport problem; use the current Podman troubleshooting guide to collect diagnostics before continuing. There is no database-side grant or ORDS change that repairs this failure.

On macOS, Podman’s guest console log is commonly located at ${TMPDIR}/podman/<machine-name>.log. Search it for common ignition and readiness markers:

grep -nE 'Ignition has failed|ignition-files.service|useradd: cannot lock|systemd-fsck-root|ready.service|multi-user.target' "${TMPDIR}/podman/<machine-name>.log"

No matching output means those markers were not found. If the guest entered emergency mode, preserve the machine disk and all database volumes while resolving the Podman VM startup problem. Do not initialize another machine or remove an existing machine until its database data has been accounted for.

If the log specifically reports useradd: cannot lock /etc/group; try again later, the failure is in Podman’s guest Ignition setup, before ADB-Free starts. One earlier macOS/arm64 validation on Podman 6.1.0 was resolved after upgrading to 6.1.3 and creating a replacement machine with no database data. However, on 2026-10-09 the same error reproduced on Podman 6.1.3 with the 6.1 machine image (Fedora CoreOS 44.20260829.3.1), so that upgrade is not a confirmed fix for every setup. Podman issue 28439 reports the same Apple Silicon/macOS pattern, including LastUp: Never, a failed podman info, and the same Ignition user-lock message. That report was filed against Podman 5.8.1 and remains open with no maintainer-confirmed fix. Its author suspects overlapping setup of the core account by Podman and FCOS, but this is unconfirmed and is not a user workaround. The upstream report also reproduced the failure after creating a fresh machine from the same cached image, so repeatedly recreating a machine may not help. This run reproduced the error on Podman 6.1.3. Preserve the machine log and disk and collect diagnostics for the upstream issue before changing or recreating the machine. For other versions, use a current Podman patch release supported by your platform and confirm podman info succeeds. Keep the failed machine disk until you have confirmed it contains no database volume or other data you need.

A host port is already in use

Find the process using the host port, then change only the host-side port in the -p option. Keep the container-side port unchanged. For example, change -p 8443:8443 to -p 9443:8443 and use https://localhost:9443 in both the Console URL and SDK REST endpoint.

Do not change the container-side database or ORDS ports unless the image documentation explicitly requires it.

Container ports are published on all interfaces

Check the current port bindings for your runtime:

docker port adb-free
podman port adb-free

The short -p 8443:8443 form used in the parent page follows Oracle’s image example and publishes on all host network interfaces by default. Check the actual binding with the command for your runtime above. If you want access only from the same computer, use the optional loopback form -p 127.0.0.1:8443:8443 for ORDS (and the corresponding form for each other published port). The image uses self-signed certificates, so choose the binding that matches your local network policy. Port bindings cannot be changed on an existing container: recreate the container with the same OracleDBData volume attached. Do not remove or rename the volume when changing port bindings.

Database Actions times out or sign-in fails

If https://localhost:8443/ords/admin/_sdw/?nav=worksheet times out, try the following options:

  1. Open the URL in another browser. If your browser uses a proxy, add localhost, 127.0.0.1, and ::1 to its proxy bypass list, or use the direct connection check below.
  2. If localhost name resolution is the problem, try the IPv4 loopback URL: https://127.0.0.1:8443/ords/admin/_sdw/?nav=worksheet.

  3. Do not use the IPv6 literal https://[::1]:8443/ords/admin/_sdw/?nav=worksheet to sign in. It may display the sign-in page, but authentication fails. Use the localhost URL for the browser session. localhost and [::1] are different hostnames; if ORDS redirects between them, the browser may not reuse a host-scoped session cookie. This is a likely explanation, but the exact cause requires the browser’s network response or ORDS logs to confirm. If sign-in also fails at localhost, check the database username, password, and ORDS schema mapping; Oracle requires the Database Actions user schema to be REST-enabled. See Oracle Database Actions sign-in requirements.

    To verify that the service is reachable over IPv6 while keeping the localhost hostname, run this optional check:

    curl -6 --noproxy '*' -k -sS -o /dev/null -w 'HTTP %{http_code}\n' 'https://localhost:8443/ords/'

    -6 forces this check to use IPv6, while the URL keeps localhost as the host name. An HTTP status confirms that the IPv6 connection reached ORDS. Then open the localhost Database Actions URL in the browser. If the check reports a connection error, use the IPv4 URL or check the published port.

  4. Check the ORDS port using the Docker or Podman tab in the published-port troubleshooting section. Use the host port shown in the output in the URL. If there is no ORDS port binding, follow the port-binding steps in that section.

  5. To check IPv4 connectivity without browser proxy settings, run this optional command. It bypasses configured proxies and ignores the local self-signed certificate for this check only:

    curl --noproxy '*' -k -sS -o /dev/null -w 'HTTP %{http_code}\n' 'https://127.0.0.1:8443/ords/'

    Replace 8443 with the host port reported by the runtime’s port command in step 4 if it differs. An HTTP status means the host reached ORDS; if the command times out or reports a connection error, check that the container is running and ORDS has finished starting. See startup diagnostics.

The container name is already in use

Check whether an adb-free container exists and confirm that it belongs to this ADB-Free setup before inspecting or removing it:

docker ps -a --filter name=adb-free
podman ps -a --filter name=adb-free

If the container exists, pull the latest image and compare its image ID with the ID used by the existing container. Run these commands with the matching runtime. If the pull fails, see registry and proxy troubleshooting:

docker pull ghcr.io/oracle/adb-free:latest-26ai
docker inspect --format '{{.Image}}' adb-free
docker image inspect --format '{{.Id}}' ghcr.io/oracle/adb-free:latest-26ai
podman pull ghcr.io/oracle/adb-free:latest-26ai
podman inspect --format '{{.Image}}' adb-free
podman image inspect --format '{{.Id}}' ghcr.io/oracle/adb-free:latest-26ai

If the IDs differ, the existing container uses an older image. Remove only the stale container with the matching runtime, then repeat Step 3 to create it from the latest image. This preserves the OracleDBData volume and database. Reapply any ORDS settings or other changes stored only in the container filesystem:

docker rm -f adb-free
podman rm -f adb-free

If the IDs match, skip removal and continue with the existing container; it already uses the latest image. If the container does not exist, skip the comparison and removal steps. If the OracleDBData volume is missing, repeat Step 2 before creating the container. If adb-free belongs to another application, do not remove it; resolve the name conflict separately.

If the database state is inconsistent and you want a completely clean setup, follow Reset and recovery to remove the old container and the OracleDBData volume. This permanently deletes the local database and its stored state.

The container exits, restarts, or reports no space

Check the logs and available runtime space for your runtime:

docker logs --tail 300 adb-free
docker exec adb-free df -h
docker system df
podman logs --tail 300 adb-free
podman exec adb-free df -h
podman system df

The ADB-Free database has a fixed 20 GB database-storage limit. Runtime storage also holds image layers, wallet files, logs, and other containers; a Podman machine or Docker Desktop additionally uses disk for its guest system. If runtime storage is full, free or increase that storage while retaining OracleDBData. Do not increase the database quota to solve a full runtime disk.

If the container was recreated with a different volume name, the original database is not visible. Reuse OracleDBData when the original database is required.

The container runtime or database runs out of memory

Memory pressure can make database initialization, ORDS startup, model loading, or vector-index creation slow or fail. Check the runtime allocation and host pressure before increasing values:

docker info
docker stats --no-stream adb-free
podman machine inspect
podman stats --no-stream

The documented setup allocates 8 GB of memory to the Podman machine. In Docker Desktop, check Settings > Resources. Increase the runtime allocation to 16 GB only if the workload requires it and the host has sufficient physical memory. Leave capacity for the host operating system and tools. More runtime memory cannot increase the database’s fixed service limits.

Shared-memory errors or failed model/index operations

Check the container shared-memory filesystem for your runtime:

docker exec adb-free df -h /dev/shm
podman exec adb-free df -h /dev/shm

The parent setup command sets --shm-size=4g for vector and model work. If /dev/shm is full, increase the value. This option is fixed when the container is created; changing it requires recreating the container while preserving OracleDBData.

Another Free database is already running

Only one process can bind a given host port. List containers and stop the unrelated container or choose different host-side ports. Do not remove a container or volume until you have confirmed which database it contains.

Database startup, ORDS, and permissions

Use these steps for database initialization, ORDS readiness, and required schema privileges.

ORDS does not initialize

Wait for the first initialization to finish before repeatedly restarting the container. Inspect recent logs and the bundled ORDS version for your runtime:

docker logs --tail 300 adb-free
docker inspect adb-free --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}no healthcheck{{end}}'
docker exec adb-free ords --version
podman logs --tail 300 adb-free
podman inspect adb-free --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}no healthcheck{{end}}'
podman exec adb-free ords --version

Use the read-only version check in ORDS configuration details. This setup intentionally uses the image-bundled ORDS runtime and does not replace ords.war. If the version is below the SDK minimum, follow the conditional image update guidance there; changing a pool limit does not upgrade ORDS. If startup logs report a wallet, database-service, or ORDS metadata error, preserve the volume and resolve that specific error before retrying.

A healthy /ords/ page only confirms that the ORDS listener is responding. If a vector schema URL returns 404, check that the schema exists and that its lowercase mapping was created by the parent page’s ORDS_ADMIN.ENABLE_SCHEMA step.

During first startup, ORA-12154 can appear before the image creates wallet TNS aliases, followed by a transient ORA-01017 while the database is still starting. Check the health state with the command above and wait until it is healthy; the repository setup launcher retries the transient login error while health is starting. If you are following the manual steps, wait and retry the login after the wallet aliases exist. If ORA-12154 persists after the container is healthy, confirm that SQL*Plus uses the generated wallet directory for TNS_ADMIN and that the requested service alias exists in its tnsnames.ora. If ORA-01017 continues after health is complete, verify that ADMIN_PASSWORD matches the password used to initialize this database volume. Interactive setup verifies a supplied existing password before saving it. Do not remove or reset the volume to work around this error.

Startup logs include ORA-01031 from the PDB plug job

The latest-26ai image can log ORA-12012 and ORA-01031 from C##CLOUD$SERVICE.PLUG_CONTAINER_PDB_JOB during startup, and may also report ORA-32004 for an obsolete or deprecated initialization parameter. In a validated setup, these messages appeared even though the PDB was plugged, the ORDS pool became VALID, the container became healthy, and REST Enabled SQL verification passed. Treat these log entries as non-blocking only when those readiness checks also succeed; the log line by itself does not call for a manual SYS grant.

If the container stays unhealthy, ORDS reports an invalid pool, or the PDB never becomes available, preserve OracleDBData and inspect the complete startup log before taking database-side action. Do not grant additional privileges to C##CLOUD$SERVICE or SYS just to suppress the message.

Vector loads fail with ORA-06564 for DATA_PUMP_DIR

A DBMS_CLOUD-backed vector-load request can be accepted and create a job, but the asynchronous job fails when the vector schema lacks READ and WRITE on the Oracle directory object DATA_PUMP_DIR. The job log may include:

ORA-20000: ORA-06564: Object DATA_PUMP_DIR does not exist or is not accessible to the user.
ORA-06512: at "SYS.DBMS_VECTOR_DATABASE", ...
ORA-06512: at "C##CLOUD$SERVICE.DBMS_CLOUD$BASE", ...

This is a database directory privilege problem. Changing host filesystem permissions, the SDK endpoint, or TLS verification does not grant access.

Connect as ADMIN and check that the directory exists and that the vector user has both privileges:

SELECT directory_name
FROM dba_directories
WHERE directory_name = 'DATA_PUMP_DIR';

SELECT grantee, privilege
FROM dba_tab_privs
WHERE table_name = 'DATA_PUMP_DIR'
  AND type = 'DIRECTORY'
  AND grantee = UPPER('<VECTOR_USER>')
ORDER BY privilege;

The first query should return DATA_PUMP_DIR; the second should show READ and WRITE. If either grant is missing, run this as ADMIN, after replacing the placeholder with the actual schema name:

GRANT READ, WRITE ON DIRECTORY DATA_PUMP_DIR TO <VECTOR_USER>;

Grant these privileges only to the schema that runs the vector jobs; do not grant them to PUBLIC. If DATA_PUMP_DIR itself is absent, investigate database initialization instead of creating a directory with an arbitrary host path.

The database user is locked, lacks quota, or cannot call the API

Use Database Actions as an administrator to check the user status, DATA tablespace usage, quota, and ORDS mapping. The parent SQL unlocks a user only if the setup variant includes that statement; otherwise unlock the schema explicitly after confirming the password and security policy.

The schema needs the parent page’s VecDB development role, DBMS_CLOUD access for database cloud operations, read/write access to DATA_PUMP_DIR when required, and the ORDS mapping created by ORDS_ADMIN.ENABLE_SCHEMA. The vector schema is not the ORDS runtime account; do not provision it with ORDS_ADMIN.PROVISION_RUNTIME_ROLE. Do not add obsolete package or inherit-privilege grants from older setup variants.

ORDS uses too many database sessions

ADB-Free supports up to 30 simultaneous database sessions. A pool maximum of 30 with no reserved headroom can leave no capacity for direct SQL, SDK workers, or maintenance. Check the current pool values for your runtime:

docker exec adb-free ords --config /u01/ords config get jdbc.InitialLimit
docker exec adb-free ords --config /u01/ords config get jdbc.MaxLimit
podman exec adb-free ords --config /u01/ords config get jdbc.InitialLimit
podman exec adb-free ords --config /u01/ords config get jdbc.MaxLimit

Use an initial limit of 8 and a maximum of 20 for the documented local profile, which leaves room for non-ORDS connections. See ORDS pool sizing for when to adjust those values and what the settings control. Apply the settings and restart the container with your runtime to take effect:

docker exec adb-free ords --config /u01/ords config set jdbc.InitialLimit 8
docker exec adb-free ords --config /u01/ords config set jdbc.MaxLimit 20
docker restart adb-free
podman exec adb-free ords --config /u01/ords config set jdbc.InitialLimit 8
podman exec adb-free ords --config /u01/ords config set jdbc.MaxLimit 20
podman restart adb-free

Restarting causes brief downtime but preserves the database when the existing OracleDBData volume remains attached.

REST endpoint, TLS, and authentication

Use these steps when the database is ready but SDK or browser requests fail.

The browser shows a certificate warning or the SDK rejects TLS

Use /u01/ords/self-signed.crt, the certificate served by ORDS on port 8443. Do not use adb_container.cert from the database wallet as the ORDS HTTPS certificate. Follow the certificate setup steps to copy it to the host, add it to the browser trust store, restart the browser, and reopen the Console URL without a warning.

Browser trust does not configure the Python SDK. Set ssl_ca_cert in Configuration to the copied certificate file so the SDK verifies the local ORDS endpoint. Use -k only for a temporary local diagnostic. If the container was recreated, copy the newly generated ORDS certificate again.

The REST endpoint returns 401 Unauthorized

An unauthenticated 401 Unauthorized response from the SDK REST endpoint is expected and confirms that ORDS is reachable and protecting the endpoint. Verify that:

Use Configuration for the REST endpoint and authentication parameters. For connection examples and credential setup, see Connect and authenticate with Python.

The vector-table endpoint returns an empty list

A successful authenticated list request with HTTP 200 and an empty items array means the schema currently has no vector tables. This is expected after creating a new vector user; create a table through the SDK or the Vector Database Console before expecting table entries. It does not indicate a missing ORDS mapping or database grant. If a table should already exist, verify that the request uses the intended vector user’s lowercase ORDS mapping.

The OAuth token request fails

Confirm that the OAuth client was created for the client-credentials grant with the oracle.dbtools.auth.roles.builtin.VecDB role, and that the token URL uses the lowercase schema mapping:

https://localhost:8443/ords/<vector_user>/oauth/token

ORDS uses an HTTP POST with client credentials and the grant_type=client_credentials form value. For a local self-signed certificate diagnostic, the request can be sent with cURL:

curl --silent --show-error --insecure \
  --user '<CLIENT_ID>' \
  --data 'grant_type=client_credentials' \
  'https://localhost:8443/ords/<vector_user>/oauth/token'

Prefer trusting the local ORDS certificate instead of --insecure outside a temporary local check. The command above supplies only the client ID; cURL prompts for the client secret. Do not put a real client secret in shell history, shared scripts, or logs. A successful request returns JSON containing an access_token; use it with the SDK’s Configuration(access_token=...) setting. The client secret is shown only when the client is created; create a replacement client if it was not stored securely. See Oracle’s ORDS client-credentials token request for the protocol example.

For the complete OAuth client and token procedure, see Configure OAuth 2.0 bearer-token authentication.

Registry, proxy, and Object Storage access

Use these steps when setup downloads or database model operations cannot reach external services.

The setup cannot reach the registry or Object Storage

Registry access is required to pull the Podman machine image and the ADB-Free container image. Object Storage access may be required when the database downloads an embedding or reranking model. Distinguish the layers:

If direct outbound access works but model loading fails, check the database-level property and the Object Storage URL or PAR used by the model operation.

Reset and recovery

Reset only when you intend to discard the current local database and its stored state.

Reset only when the database can be discarded

A clean reset permanently deletes the database, users, wallet, ORDS state, and model files stored in OracleDBData. Confirm that the data is disposable and that the commands target the intended Podman machine or Docker context. On macOS or Windows, start the existing Podman machine first; do not remove the machine to reset only this database.

Check the container and volume before removal, using the tab for your runtime:

docker ps -a --filter name=adb-free
docker volume inspect OracleDBData
podman ps -a --filter name=adb-free
podman volume inspect OracleDBData

If the container and volume are the ADB-Free setup you intend to discard, remove only those resources with the matching runtime:

docker pull ghcr.io/oracle/adb-free:latest-26ai
docker rm -f adb-free
docker volume rm OracleDBData
podman pull ghcr.io/oracle/adb-free:latest-26ai
podman rm -f adb-free
podman volume rm OracleDBData

Recreate the named volume by repeating Step 2, then continue with the container start step.

Next steps

After recovery, return to Autonomous AI Database Free Container and continue from the first incomplete step.