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?"

1. 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
• Issues deploying applications and functions
• Issues invoking functions
• Storing and Viewing Function Logs
• Function Metrics
• Functions QuickStart on Local Host