Troubleshooting

Use this page to resolve common Oracle VecDB Python SDK, ORDS, and database issues.

Common ORDS errors returned by the Oracle VecDB Python SDK.

ApiException: (429) Too Many Requests

Summary: ApiException: (429) occurs when the ORDS service cannot fulfill the request at that moment. This is a temporary service-capacity condition, not necessarily a request-schema error.

Symptoms: The SDK raises an exception similar to:

ApiException: (429)
Reason: Too Many Requests

The response body can include a message such as:

The Pool named: |default|<pool>| reached the maximum ORDS connections.

Cause: Concurrent application requests, other clients using the same ORDS pool, or long-running database work have exhausted the pool’s available connections.

Solution:

• Have the ORDS administrator size the applicable pool for the expected workload and investigate connections that are held longer than expected.
• Limit concurrent VecDB requests to a level the service can sustain.
• Keep database operations short and release client/process resources when they are no longer needed.

Workaround: Wait and retry using bounded exponential backoff with jitter. The SDK retries HTTP 429 responses up to three times by default, but those attempts are immediate. Reduce request concurrency or add application-level backoff when the pool remains full. Automatically retry only operations that are safe to repeat.

ServiceException: (555) with ORDS-25001

Summary: ORDS encountered a user-defined-resource processing error while handling a VecDB request. This can be intermittent.

Symptoms: The SDK raises an exception similar to:

ServiceException: (555)
code: UserDefinedResourceError
o:errorCode: ORDS-25001
message: The request could not be processed for a user defined resource

Cause: A transient ORDS or database-side failure can prevent the resource from processing the request. A persistent error can also indicate an endpoint or payload problem.

Solution: Verify the VecDB endpoint and request payload. If the error persists after retrying, provide the ORDS administrator or resource owner with the response instance (ECID), timestamp, endpoint, and a sanitized request shape so they can investigate ORDS-25001. Do not include credentials or sensitive application data in diagnostics.

Workaround: Retry the request with bounded exponential backoff and jitter. The SDK recognizes HTTP 555 and ORDS-25001 as transient and retries up to three times by default. Add an application-level retry policy when more delay is appropriate, and stop after a finite number of attempts.

BadRequestException: (400) Bad Request

Summary: BadRequestException: (400) means that the service could not process the request. However, this does not by itself prove that the client payload is invalid. ORDS can also map an underlying Oracle Database failure to HTTP 400.

Symptoms: The SDK raises an exception similar to:

BadRequestException: (400)
{
    "code": "BadRequest",
    "message": "<error details that caused this exception>",
    "instance": "...ecid/..."
}

Always inspect the response message and any embedded ORA- code.

Examples of client-side bad-request errors include:

ORA-11549: invalid annotation value '' in the ANNOTATIONS sequence.

ORA-20400: Invalid name. Only letters, digits, and underscore (_) are allowed.

ORA-20400: Parameter "name" exceeds 128 characters.

Examples of database-condition errors include:

ORA-01652: unable to grow lob ... in tablespace SYSEXT by .. during operation ...

ORA-65114: space usage in container is too high.

ORA-51906: Failed to create auxiliary tables for the vector index.

Cause: There are two broad possibilities:

• The request violates the VecDB API contract (for example, an invalid field, value, or combination of options).
• The database cannot complete an otherwise valid operation because of an underlying database condition, such as a space, quota, or storage issue.

Solution: First validate the request against the SDK/API documentation. Then inspect the ORA- error message. If it identifies an invalid request, correct the request; otherwise, involve the database administrator:

• For ORA-01652, inspect the named tablespace and temporary-space pressure; free space or increase the appropriate datafile/tablespace capacity and address the consuming operation.
• For ORA-65114, inspect container/PDB space usage and quotas; reclaim unused objects or increase the container’s available capacity according to the database deployment’s procedures.
• For ORA-51906, check database space and the resources required for vector index auxiliary tables before changing valid index parameters.

Use the response instance (ECID), timestamp, operation, and sanitized request shape when escalating. Do not include credentials or sensitive data in diagnostics.

Workaround: If the root cause of the 400 error is a database condition, retry the operation after that condition is resolved. Do not repeatedly retry a 400 response while an ORA- resource condition remains unresolved.

Common ORA Errors: User Actions

The following ORA errors can be resolved.

Rebuilding an HNSW Vector Index Fails

Symptoms

Rebuilding a Hierarchical Navigable Small World (HNSW) index for a vector table can fail with the following error:

ORA-20003: Organization in the index creation DDL is invalid

The index rebuild does not complete successfully.

Affected Versions

Oracle AI Database 23.26.3.

Cause

In the affected release, rebuilding an HNSW vector index can generate invalid index-creation DDL.

Workaround

Drop and recreate the vector index:

1. Record the existing vector-index definition and parameters.
2. Drop the affected index.
3. Recreate the index.
4. Use the same index definition and parameters that were intended for the rebuild operation.
5. Confirm that the recreated index is available and valid before resuming application traffic.

Caution: Dropping the index temporarily removes indexed vector-search capability. Plan the operation for an appropriate maintenance window.

Resolution

This issue is resolved in Oracle AI Database 23.26.4 and later releases.

Upgrade to a fixed release before rebuilding affected HNSW indexes.

Verification

After upgrading, run the rebuild operation again and confirm that:

• The operation completes without ORA-20003.
• The vector index is created successfully.
• Vector-search queries can use the rebuilt index.

Common ORA Errors: Administrator Actions

The following ORA errors require action by a database administrator or a user with the required administrator privileges.

Loading Vectors Fails with ORA-00910

Symptoms

Loading vector data can fail with the following error:

ORA-20000: ORA-00910: specified length too long for its datatype

This problem can occur when loading vector data from an external URL.

Cause

The database is configured with:

MAX_STRING_SIZE=STANDARD

Loading vectors requires extended SQL string-size support for this operation. A database configured with MAX_STRING_SIZE=STANDARD does not provide the required capacity.

Diagnosis

A database administrator can check the current setting by running:

SELECT value
FROM   v$parameter
WHERE  name = 'max_string_size';

If the query returns STANDARD, the database does not meet this requirement.

Solution

1. Ask the database administrator to review the impact of enabling extended data types.
2. Follow the documented procedure for changing MAX_STRING_SIZE from STANDARD to EXTENDED.
3. Complete all required database upgrade and validation steps.
4. Run the parameter query again and confirm that it returns EXTENDED.
5. Retry the load operation.

Example

Before the database change:

SELECT value
FROM   v$parameter
WHERE  name = 'max_string_size';

-- Result:
-- STANDARD

After the database change:

SELECT value
FROM   v$parameter
WHERE  name = 'max_string_size';

-- Result:
-- EXTENDED

Verification

Confirm that the parameter is set correctly:

SELECT value
FROM   v$parameter
WHERE  name = 'max_string_size';

Expected result:

EXTENDED

Retry the load operation and confirm that it completes without ORA-00910.

Important Considerations

Changing MAX_STRING_SIZE is a database-administration operation that requires the documented upgrade procedure. It is not equivalent to changing an ordinary dynamic initialization parameter.

Changing MAX_STRING_SIZE from STANDARD to EXTENDED is a one-way operation. After it is set to EXTENDED, it cannot be changed back to STANDARD.

Enabling extended data types can affect existing database objects and application compatibility. The database administrator should review the documented prerequisites, including the required COMPATIBLE setting and post-change scripts, before proceeding.

Related Information

See the MAX_STRING_SIZE parameter documentation.

Creating a Vector Table Fails with ORA-29833

Symptoms

Creating a vector table can fail with the following error:

ORA-29833: The indextype does not exist

Cause

Creating a vector table can also create a default metadata search index. This index depends on the Oracle Text component.

The operation fails if Oracle Text is:

• Not installed.
• Not enabled.
• Installed but invalid.

Diagnosis

A database administrator can check the status of Oracle Text by running:

SELECT comp_name,
       status,
       version
FROM   dba_registry
WHERE  comp_id = 'CONTEXT';

The query should return an Oracle Text component whose status is VALID.

If no row is returned, Oracle Text might not be installed. If the status is not VALID, the component requires administrative attention.

Note: Access to DBA_REGISTRY typically requires database-administration privileges.

Solution

1. Confirm that Oracle Text is installed in the target Oracle AI Database.
2. Confirm that the Oracle Text component has a VALID status.
3. If Oracle Text is unavailable or invalid, ask the database administrator to install, enable, repair, or validate it as appropriate.
4. Retry the vector table creation after Oracle Text becomes available.

Verification

Run the component-status query again and confirm that the status is VALID.

Create the vector table again and confirm that:

• The vector table is created.
• The requested vector index is created.
• The default metadata search index is created successfully.
• The operation completes without ORA-29833.

Related Information

See Oracle Text installation and configuration.