# oci-functions-troubleshoot

> Diagnose OCI Functions setup, control-plane, deployment, invocation, and observability issues using a deterministic triage workflow.

- Skill: `oracle/oci-functions-troubleshoot` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds add oracle/oci-functions-troubleshoot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oracle/oci-functions-troubleshoot/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra, Security, Cloud Platforms, Monitoring & Observability
- Tags: Diagnosis, Fn Cli, Functions, Observability, Oci, Oracle Cloud, Troubleshooting
- Author: Oracle (https://skillmd.com/u/oracle), verified publisher
- Updated: 2026-07-06
- Page: https://skillmd.com/skills/oracle/oci-functions-troubleshoot

---


# OCI Function Troubleshoot

Use this skill to isolate the most likely cause of an OCI Functions problem from error text, command output, or observability signals.

This skill is diagnosis-first and non-mutating by default:
- prefer read-only checks
- do not edit Fn context, log into Docker, create or update apps, redeploy, or change infrastructure unless the user explicitly asks to execute a fix
- if the user wants the fix executed, finish the diagnosis first and hand off mutating remediation to `$oci-functions-deploy`

## Output Contract

Always answer in this exact shape:
- `stage`: one of `setup_or_control_plane`, `create`, `deploy`, `invoke`, `observability_first`
- `evidence`: 1-3 concrete facts from the user's error text, command, config, logs, metrics, or limits
- `most_likely_cause`: one primary cause, or a ranked top-2 shortlist when confidence is low
- `confidence`: `low`, `medium`, or `high`
- `next_confirming_check`: the single best read-only check to narrow or confirm the cause
- `smallest_safe_remediation`: the least invasive next action; if evidence is weak, this can be "collect more evidence with ..."
- `validation`: the follow-up step that proves the remediation worked

## Triage

1. If the user provides an exact error string, start with `references/error-patterns.md`.
2. Classify the issue from the failed action:
- `setup_or_control_plane`: local Fn/OCI/OCIR/tooling/auth/context/policy problems before normal app or function operations succeed
- `create`: application creation failures
- `deploy`: `fn deploy`, image build or push, `func.yaml`, app config, subnet annotation, or registry-target failures
- `invoke`: runtime invocation, HTTP, image pull, timeout, memory, networking, detached delivery, or response-limit failures after a function has been deployed
- `observability_first`: the user starts from logs, traces, metrics, limits, or "why is this function unhealthy?"
3. If the stage is ambiguous:
- ask exactly one disambiguating question when a single missing fact would change the stage
- otherwise present the top 2 plausible stages in ranked order and continue with the best read-only confirming check

## Minimum Facts

Capture the minimum facts before diagnosing:
- exact error text and HTTP status if present
- command or action that failed
- region, compartment/profile, app name, and function name if known
- whether the problem is local, deploy-time, invoke-time, or telemetry-first
- whether Fn CLI, OCI CLI, Docker, Logging, Monitoring, and Tracing access are available

## Preferred Read-Only Checks

Prefer non-mutating checks when tooling is available:
- `fn inspect context`
- `fn list apps`
- `fn inspect app <app-name>`
- `fn inspect function <app-name> <function-name>`
- read local `func.yaml`
- inspect environment values that can override expected behavior, especially `FN_REGISTRY`
- read logs, traces, metrics, and limits before recommending edits
- use `DEBUG=1` or `OCI_GO_SDK_DEBUG=v` only for additional diagnostic signal, not as a first fix

If tools or access are missing, stay docs-first:
- classify the failure from the error text
- use the phase reference file for likely causes
- use `references/error-patterns.md` when the text is the strongest clue

## Workflow

### Setup Or Control Plane

Use `references/setup-and-runtime.md` for:
- Fn CLI `401` and `404`
- OCI key, passphrase, and private key format problems
- wrong region, compartment, endpoint, or app/function target
- IAM, policy, dynamic-group, or network-resource authorization failures
- Docker registry unauthorized failures
- stale or outdated CLI behavior

Start with read-only checks:
- inspect active Fn context values
- verify the intended OCI profile, compartment, and region match the failing target
- confirm the registry host derived from the context
- for `404`, separate endpoint or name mismatches from IAM/policy or compartment-targeting issues before suggesting reconfiguration

### Application Creation

Use `references/create.md` for create-time failures.

Focus on:
- documented service-limit style failures such as maximum application count
- whether the request is going to the intended compartment and region
- whether IAM or compartment targeting is wrong when the error is not clearly limit-shaped
- whether the smallest safe path is reuse, cleanup, or a limit increase request

### Deployment

Use `references/deploy.md` for:
- `fn deploy` failures
- image build, push, or registry auth problems
- `func.yaml` schema issues
- wrong application context or missing subnet annotations
- architecture mismatch symptoms
- identity-domain or federated OCIR username issues

Check in this order:
- active Fn context and target app
- local `func.yaml`
- effective registry target, including `FN_REGISTRY`
- app annotations and subnet/network assumptions
- whether the failure is local build, image push, or service-side deploy
- `fn version` when architecture or stale-client symptoms are plausible

### Invocation

Use `references/invoke.md` for:
- request or response size limits
- throttling, detached delivery, or event-triggered retries
- client disconnect, image pull, DNS, timeout, memory, syslog, security-attribute, or dynamic-group failures
- subnet, DHCP, resolver, or service-availability failures

Check in this order:
- exact HTTP code and service error text
- whether the error happens before code starts, during init, during execution, or after execution but before delivery completes
- logs first for code/runtime clues when available
- traces next when enabled and downstream timing or dependency timing is unclear
- metrics next for error rate, latency, concurrency, and invoke-type trends
- limits last when the symptom suggests capacity pressure or service ceilings

### Observability First

Use `references/observability.md` when the user starts from symptoms instead of a single failing command.

Default observability sequence:
1. Logs: determine whether the function ran and whether application logging is enabled
2. Tracing: use traces when enabled and the missing clue is dependency timing, latency, or call path
3. Metrics: distinguish execution failure, throttling, detached delivery, latency, and capacity pressure
4. Limits: confirm whether create or invoke failures align with service limits
5. Debug flags: use `DEBUG=1` or `OCI_GO_SDK_DEBUG=v` only when reproducing locally or when request/SDK details are still missing

## Reference Map

- setup/control-plane issues: `references/setup-and-runtime.md`
- app creation issues: `references/create.md`
- deployment issues: `references/deploy.md`
- invocation issues: `references/invoke.md`
- logs, traces, metrics, limits, debug flags: `references/observability.md`
- exact strings to likely causes: `references/error-patterns.md`
- reusable prompt patterns: `references/example-prompts.md`

## Guardrails

- Diagnose and isolate first. Do not mutate local context, Docker auth, app config, deployed state, or infrastructure unless the user explicitly asks to execute a fix.
- If the user asks to execute the fix, complete the diagnosis summary first and hand off mutating repair work to `$oci-functions-deploy`.
- Do not start with mutating fixes when a read-only check can narrow the cause.
- Do not assume a `404` is only an endpoint or name problem; treat IAM, policy, compartment targeting, dynamic groups, and network-resource authorization as first-class alternatives.
- Do not assume a deploy issue is code-related until registry, app, client version, and network context are checked.
- Do not assume an invoke issue is platform-related until logs, traces, and metrics are checked.
- Treat `FN_REGISTRY`, active Fn context, app annotations, tracing availability, and service limits as common hidden causes.
- If the user gives only a partial symptom, ask for the exact error text or failing command before escalating to broad remediation.
- When evidence is partial, prefer a ranked shortlist of plausible causes over a single overconfident root cause.

## Sources

- [Troubleshooting OCI Functions](https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functionstroubleshooting.htm)
- [Issues deploying applications and functions](https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functionstroubleshooting_topic-Issues-deploying-applications-and-functions.htm)
- [Issues invoking functions](https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functionstroubleshooting_topic-Issues-invoking-functions.htm)
- [Storing and Viewing Function Logs](https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functionsexportingfunctionlogfiles.htm)
- [Function Metrics](https://docs.oracle.com/en-us/iaas/Content/Functions/Reference/functionsmetrics.htm)
- [Functions QuickStart on Local Host](https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functionsquickstartlocalhost.htm)