Oracle Cloud Common Errors

Overview

OCI API errors are notoriously cryptic.

NotAuthorizedOrNotFound

NotAuthenticated

CERTIFICATE_VERIFY_FAILED

Purpose: A diagnostic decoder ring mapping every common OCI error to its real root cause and fix, with runnable diagnostic commands for each scenario.

Prerequisites

• An OCI account with

  ~/.oci/config

  configured (see

  oraclecloud-install-auth

  )
• Python 3.8+ with

  pip install oci

  installed
• OCI CLI installed (

  pip install oci-cli

  ) for diagnostic commands

Instructions

Authentication Errors (401 NotAuthenticated)

The 401 error has six distinct root causes. Run this diagnostic to isolate which one:

import oci
import os

def diagnose_auth():
    """Diagnose OCI 401 NotAuthenticated errors."""
    config_path = os.path.expanduser("~/.oci/config")

    # Check 1: Config file exists
    if not os.path.exists(config_path):
        return "CAUSE: Config file missing. Run: oci setup config"

    config = oci.config.from_file(config_path)

    # Check 2: All required fields present
    required = ["user", "fingerprint", "tenancy", "region", "key_file"]
    for field in required:
        if field not in config or not config[field]:
            return f"CAUSE: Missing field '{field}' in ~/.oci/config"

    # Check 3: Key file exists
    key_path = os.path.expanduser(config["key_file"])
    if not os.path.exists(key_path):
        return f"CAUSE: Key file not found: {key_path}"

    # Check 4: Key is private (not public)
    with open(key_path, "r") as f:
        first_line = f.readline().strip()
    if "PUBLIC" in first_line:
        return "CAUSE: key_file points to PUBLIC key. Use the private key (no _public suffix)"

    # Check 5: Key file permissions
    perms = oct(os.stat(key_path).st_mode)[-3:]
    if perms != "600":
        return f"CAUSE: Key permissions are {perms}. Run: chmod 600 {key_path}"

    # Check 6: Fingerprint matches
    return "Config looks valid. Fingerprint mismatch? Verify in Console > User Settings > API Keys"

print(diagnose_auth())

401 Root Cause Table:

did not find a proper configuration for user

~/.oci/config

oci setup config

could not find private key

key_file

private key does not match

key_file points to public key

key_file=~/.oci/oci_api_key_public.pem

key_file=~/.oci/oci_api_key.pem

permission denied reading key

chmod 600 ~/.oci/oci_api_key.pem

InvalidKeyId

Authorization Errors (404 NotAuthorizedOrNotFound)

This is the most confusing OCI error. A 404 means either the resource does not exist or you lack IAM permission to see it. OCI hides the distinction intentionally.

Diagnostic steps:

# Step 1: Verify the OCID format is correct
echo "ocid1.instance.oc1.iad.aaaa..." | grep -P '^ocid1\.\w+\.oc1\.'

# Step 2: Verify you can list resources in the compartment
oci compute instance list --compartment-id <COMPARTMENT_OCID> --limit 1

# Step 3: Check IAM policies affecting your user
oci iam policy list --compartment-id <TENANCY_OCID> --all \
  --query "data[?contains(statements[0], 'instances')]"

Common IAM policy fixes:

# Allow a group to manage compute in a compartment
allow group Developers to manage instances in compartment MyCompartment

# Allow a group to read all resources (useful for debugging)
allow group Developers to read all-resources in tenancy

SSL Certificate Errors (CERTIFICATE_VERIFY_FAILED)

# Diagnostic: check which CA bundle Python uses
import ssl
print(ssl.get_default_verify_paths())

# Fix 1: Install/update certifi
# pip install --upgrade certifi

# Fix 2: Point to system CA bundle (Linux)
import os
os.environ["REQUESTS_CA_BUNDLE"] = "/etc/ssl/certs/ca-certificates.crt"

# Fix 3: Corporate proxy — add proxy CA to certifi bundle
# cat proxy-ca.pem >> $(python -c "import certifi; print(certifi.where())")

SSL Fix by Environment:

pip install --upgrade certifi

brew install ca-certificates

COPY ca-bundle.crt /etc/ssl/certs/

REQUESTS_CA_BUNDLE

Rate Limit Errors (429 TooManyRequests)

OCI does not send a

Retry-After

import oci
import time
import random

def handle_rate_limit(fn, max_retries=5):
    """Handle OCI 429 errors. No Retry-After header — use jittered backoff."""
    for attempt in range(max_retries):
        try:
            return fn()
        except oci.exceptions.ServiceError as e:
            if e.status == 429:
                delay = (2 ** attempt) + random.uniform(0, 2)
                print(f"Rate limited. Waiting {delay:.1f}s (attempt {attempt + 1})")
                time.sleep(delay)
            else:
                raise
    raise RuntimeError("Rate limit retries exhausted")

# Or use the built-in strategy
compute = oci.core.ComputeClient(
    config, retry_strategy=oci.retry.DEFAULT_RETRY_STRATEGY
)

Timeout Errors (ServiceError status -1)

A

ServiceError

status == -1

import oci

config = oci.config.from_file("~/.oci/config")

# Default has NO connection timeout. Always set both:
compute = oci.core.ComputeClient(
    config,
    timeout=(10, 60)  # (connect_timeout, read_timeout)
)

# Object Storage uploads need longer read timeout
object_storage = oci.object_storage.ObjectStorageClient(
    config,
    timeout=(10, 600)  # 10 min for large uploads
)

Internal Server Errors (500 InternalError)

import oci

# Check OCI service health first
# https://ocistatus.oraclecloud.com

# 500 errors are transient — use retry strategy
compute = oci.core.ComputeClient(
    oci.config.from_file("~/.oci/config"),
    retry_strategy=oci.retry.DEFAULT_RETRY_STRATEGY  # Retries 500, 502, 503, 504
)

Output

After working through this diagnostic guide you will have:

• Identified the exact root cause of your OCI error from the error code and message
• A runnable diagnostic script for 401 auth errors that checks all six failure modes
• IAM policy statements to resolve 404 authorization errors
• Correct timeout and retry configuration for 429 and 500 errors
• SSL certificate fixes for your specific environment

Error Handling

Complete OCI Error Reference Table:

ServiceError

diagnose_auth()

ServiceError

ServiceError

ServiceError

ServiceError

timeout=(connect, read)

SSLError

ServiceError

ServiceError

oraclecloud-hello-world

Examples

One-command connectivity test:

# Tests auth + network + SSL in one call
oci iam region list --output table 2>&1 || echo "FAILED — run oraclecloud-common-errors diagnostic"

Catch-all error handler for scripts:

import oci
import sys

config = oci.config.from_file("~/.oci/config")
compute = oci.core.ComputeClient(config)

try:
    compute.list_instances(compartment_id=config["tenancy"])
    print("OK")
except oci.exceptions.ServiceError as e:
    print(f"OCI Error: {e.status} {e.code}")
    print(f"Message: {e.message}")
    print(f"Request ID: {e.request_id}")  # Include this in support tickets
    if e.status == 401:
        print("ACTION: Check ~/.oci/config — see oraclecloud-install-auth")
    elif e.status == 404:
        print("ACTION: Verify OCID and IAM policies — see 404 section above")
    elif e.status == 429:
        print("ACTION: Rate limited — implement backoff")
    elif e.status == -1:
        print("ACTION: Timeout — increase client timeout values")
    sys.exit(1)
except oci.exceptions.ConfigFileNotFoundError:
    print("ACTION: ~/.oci/config not found. Run: oci setup config")
    sys.exit(1)

Resources

• OCI SDK Troubleshooting — official error resolution guide
• OCI Known Issues — active bugs and workarounds
• OCI Status Page — real-time service health dashboard
• OCI API Reference — error response schemas per service
• OCI Python SDK Reference — exception class hierarchy
• OCI IAM Policies — policy syntax for 404 fixes

Next Steps

Once errors are resolved, see

oraclecloud-sdk-patterns

oraclecloud-local-dev-loop