Skip to main content

Startup Time​

Problem: After starting the AI Optimizer, it takes a long time to load the first page.

Solution: Check the required Oracle AI Database connection and its startup configuration. A connect descriptor with retry_count and retry_delay can keep the connection attempt active for retry_count * retry_delay. Correct the connection and restart the Server.

Embedding Rate Limits​

Problem: During embedding, especially when using trial keys, the model provider may return a rate-limit error. For example:

Operation Failed: Unexpected error: status_code: 429, body:
data=None message='trial token rate limit exceeded, limit is 100000 tokens per minute'.

Solution: Under Tools > Split/Embed, reduce Rate Limit (RPM) to pace embedding batches within the provider quota. See Populate Vector Store.

Testbed Evaluation​

Problem: During the Evaluation in the Testbed, a database error occurs: DPY-4011: the database or network closed the connection

Solution: DPY-4011 means the database or network closed the connection. Check the Server logs for an accompanying Oracle error, then verify database availability and the network path. If the database reports vector-memory or resource pressure, increase vector_memory_size; for Oracle Autonomous Database, scale the compute resources. See DPY-4011 troubleshooting.

Autonomous Database Through a Forward Proxy​

Problem: A corporate network requires the Oracle Autonomous Database TLS connection to use a forward proxy.

Solution: Update the database connection string to include a https_proxy and https_proxy_port.

For example:

ADB_HIGH =
(DESCRIPTION =
  (ADDRESS =
    (PROTOCOL = tcps)(HOST = <adb_host>)(PORT = 1522)
    (HTTPS_PROXY = <proxy_host>)(HTTPS_PROXY_PORT = <proxy_port>)
  )
  (CONNECT_DATA =
    (SERVICE_NAME = <serviceName>)
    (SECURITY =
      (ssl_server_dn_match=yes)
    )
  )
)

Client Fails to Load on Corporate Networks​

Problem: The AI Optimizer Client fails to load in certain network environments. The browser console shows a JavaScript file (index.<hash>.js) blocked with NS_ERROR_CORRUPTED_CONNECTION (Firefox) or a similar connection error.

Solution: Enable HTTPS on the Client so its pages and JavaScript assets use an encrypted connection. If the problem continues, ask the network administrator to check the firewall, deep packet inspection, or SSL inspection logs. See TLS / HTTPS for configuration details.

MCP Client Connections​

Server Returns 403​

Problem: An MCP client receives 403 Forbidden when connecting to the AI Optimizer Server.

Solution: Check the response body:

  • {"detail":"Forbidden"} indicates a missing or incorrect X-API-Key. Generate the configuration for the selected client again and re-import it. For a standalone deployment, confirm that the configuration uses the same value as AIO_API_KEY.
  • Forbidden Origin indicates that the request includes an Origin header. Connect with a native or server-side MCP client. Browser JavaScript uses the REST API. See External MCP Clients.

Connection Is Refused​

Problem: An MCP client cannot connect to the AI Optimizer Server.

Solution: Confirm that the server is running and that the generated MCP URL is reachable from the client. Generate the configuration again if the server address or URL prefix has changed.

Tools Are Not Visible​

Problem: An MCP client connects successfully but does not show the expected tools.

Solution: Follow Verify the Connection to check the MCP health and tools endpoints. For NL2SQL, confirm that SQLcl is available and a database is configured. See SQLcl MCP Server.

Claude Desktop Cannot Start the Bridge​

Problem: Claude Desktop cannot start the generated mcp-remote configuration.

Solution: Confirm that npx is available to Claude Desktop. If necessary, use the full path to npx in the generated configuration.

Observability​

Telemetry Does Not Initialize​

Problem: The server does not log OTel telemetry initialized at startup, or it logs OTLP grpc exporter requested but not installed.

Solution: Install the optional dependencies with uv sync --extra server --extra otel. Then configure an OTLP endpoint with OTEL_EXPORTER_OTLP_ENDPOINT, or set OTEL_TRACES_EXPORTER=console for local debugging. If an OTLP exporter remains unavailable after installation, check the startup logs for a not installed; skipping warning.

Traces Do Not Reach the Backend​

Problem: The server logs OTel telemetry initialized, but traces do not appear in the backend.

Solution: For a plaintext gRPC collector, set OTEL_EXPORTER_OTLP_INSECURE=true. Alternatively, configure OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf with an http:// endpoint. Confirm that the server can reach the collector's OTLP port.

Resource Attributes Are Missing​

Problem: A value supplied through OTEL_RESOURCE_ATTRIBUTES is not visible on spans.

Solution: Use a comma-separated list of key=value pairs, without spaces or semicolons. For example:

OTEL_RESOURCE_ATTRIBUTES=k1=v1,k2=v2

Requested Exporter Is Ignored​

Problem: Setting OTEL_TRACES_EXPORTER does not produce the expected exporter behavior.

Solution: Use only the supported values: otlp, console, or none. To export to both an OTLP backend and stdout, set OTEL_TRACES_EXPORTER=otlp,console.

For configuration details and trace investigation workflows, see Observability.