oraclecloud-common-errors

Diagnose and fix Oracle Cloud Infrastructure API errors with real error codes and proven fixes. Use when encountering OCI ServiceError exceptions, auth failures, SSL issues, or timeout errors. Trigger with "oci error", "fix oraclecloud", "debug oci", "NotAuthorizedOrNotFound", "oci 401".

インストールへ移動

リポジトリ: jeremylongshore/tons-of-skills-marketplace
ソースの最終更新活動: 2026年7月17日 22:18
検出された SKILL.md の言語: 英語
スター: 2,677
フォーク: 392

インストール方法

デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。

ソースファイルを確認

インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。

検索に戻るインストールに戻る

name	oraclecloud-common-errors
description	Diagnose and fix Oracle Cloud Infrastructure API errors with real error codes and proven fixes. Use when encountering OCI ServiceError exceptions, auth failures, SSL issues, or timeout errors. Trigger with "oci error", "fix oraclecloud", "debug oci", "NotAuthorizedOrNotFound", "oci 401".
allowed-tools	Read, Grep, Bash(oci:), Bash(pip:), Bash(openssl:), Bash(curl:)
version	1.7.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","oraclecloud","oci"]
compatibility	Designed for Claude Code

Oracle Cloud Common Errors

Overview

OCI API errors are notoriously cryptic. NotAuthorizedOrNotFound (404) could mean an IAM policy is missing or you typed the OCID wrong — the error is intentionally ambiguous for security. NotAuthenticated (401) covers six different config file problems. CERTIFICATE_VERIFY_FAILED has different fixes depending on your SDK language, OS, and whether you are behind a corporate proxy.

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]:
             

    
    key_path = os.path.expanduser(config[])
      os.path.exists(key_path):
         

    
     (key_path, )  f:
        first_line = f.readline().strip()
       first_line:
         

    
    perms = (os.stat(key_path).st_mode)[-:]
     perms != :
         

    
     

(diagnose_auth())

Symptom	Root Cause	Fix
`did not find a proper configuration for user`	Missing or malformed `~/.oci/config`	Recreate with `oci setup config`
`could not find private key`	`key_file` path wrong or file missing	Check path; key must exist at that location
`private key does not match`	Fingerprint in config does not match uploaded public key	Upload correct public key or regenerate pair
`key_file points to public key`	`key_file=~/.oci/oci_api_key_public.pem`	Change to `key_file=~/.oci/oci_api_key.pem` (private key)
`permission denied reading key`	Key file permissions too open	`chmod 600 ~/.oci/oci_api_key.pem`
`InvalidKeyId`	User OCID or tenancy OCID wrong	Verify OCIDs in Console > Profile > User Settings

# 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')]"

# 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

# 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())")

Environment	Fix
Linux (system Python)	`pip install --upgrade certifi`
macOS	`brew install ca-certificates` + update certifi
Corporate proxy	Add proxy CA cert to certifi bundle
Docker container	Copy CA bundle: `COPY ca-bundle.crt /etc/ssl/certs/`
Air-gapped	Set `REQUESTS_CA_BUNDLE` to local CA file

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
)

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
)

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
)

Error	Status	Exception	Root Cause	Fix
NotAuthenticated	401	`ServiceError`	Wrong config, key, or fingerprint	Run `diagnose_auth()` above
NotAuthorizedOrNotFound	404	`ServiceError`	Missing IAM policy OR wrong OCID	Check OCID format, then IAM policies
TooManyRequests	429	`ServiceError`	Rate limit exceeded	Backoff with jitter (no Retry-After header)
InternalError	500	`ServiceError`	OCI service error	Retry; check https://ocistatus.oraclecloud.com
Timeout	-1	`ServiceError`	No response in time	Set `timeout=(connect, read)` on client
CERTIFICATE_VERIFY_FAILED	—	`SSLError`	CA bundle outdated or proxy	Update certifi or set REQUESTS_CA_BUNDLE
InvalidParameter	400	`ServiceError`	Malformed request body	Check OCID format and required fields
Out of host capacity	500	`ServiceError`	No hosts available (ARM shapes)	Retry loop; see `oraclecloud-hello-world`

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

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)