Diagnose OCI Functions setup, control-plane, deployment, invocation, and observability issues using a deterministic triage workflow. Use when asked to classify Fn CLI errors, deploy or invoke failures, OCIR auth and registry issues, app-limit symptoms, logs, tracing, metrics, or limits. Diagnose first, prefer read-only checks, and do not execute fixes unless the user explicitly asks.
Diagnose OCI Functions setup, control-plane, deployment, invocation, and observability issues using a deterministic triage workflow. Use when asked to classify Fn CLI errors, deploy or invoke failures, OCIR auth and registry issues, app-limit symptoms, logs, tracing, metrics, or limits. Diagnose first, prefer read-only checks, and do not execute fixes unless the user explicitly asks.
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
If the user provides an exact error string, start with references/error-patterns.md.
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?"
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
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.
