Troubleshooting

This section helps you diagnose and fix problems with a running Fission installation. Start here when a function returns errors, a build fails, a trigger does not fire, or a component pod is unhealthy.

The fastest path to a root cause is almost always the same: confirm the control plane is healthy, then read the logs of the one component that owns the failing step. The sections below give you the commands to do that, followed by a symptom-to-first-place-to-look table you can scan quickly.

Knowing which component owns each step tells you whose log to read. A function request flows through the router and executor before reaching your code:

flowchart TB
  client["Client"]:::user -->|"<b>1.</b> HTTP request"| router["Router"]
  router -->|"<b>2.</b> asks for pod"| executor["Executor"]
  executor -->|"<b>3.</b> creates / picks"| fnPod["Function Pod"]
  router -->|"<b>4.</b> forwards request"| fnPod
  fnPod -->|"<b>5.</b> response"| router
  router -->|"<b>6.</b> response"| client
  subgraph k8s["Kubernetes Cluster"]
    router:::fission
    executor:::fission
    fnPod:::pod
  end
  classDef user fill:#ffffff,stroke:#94a3b8,color:#1f2a43
  classDef fission fill:#e8f0fe,stroke:#2d70de,color:#1f2a43
  classDef pod fill:#e6f7f1,stroke:#11a37f,color:#1f2a43,stroke-dasharray:5 3

Self-diagnose in three steps

1. Run fission check to confirm the Fission services are up and the CLI can reach the cluster.
2. Inspect the relevant pods and their logs with kubectl.
3. If you need help, capture a fission support dump and attach it to a GitHub issue.

Step 1: Run fission check

fission check verifies that the core Fission services are running and that your CLI version matches the installed server.

$ fission check

A healthy cluster reports each service as running fine:

fission-services
--------------------
√ executor is running fine
√ router is running fine
√ storagesvc is running fine
√ webhook is running fine

fission-version
--------------------
√ fission is up-to-date

When a service is down, the failing check is marked and names the deployment:

fission-services
--------------------
√ executor is running fine
√ router is running fine
× storagesvc deployment is not running
√ webhook is running fine

To validate a cluster before installing Fission, run the pre-install checks, which confirm the Kubernetes version is compatible:

$ fission check --pre

kubernetes
--------------------
√ kubernetes version is compatible

The webhook service is part of the health check. Fission’s admission webhook validates Function, Package, Environment, KubernetesWatchTrigger, and MessageQueueTrigger resources, and its failurePolicy is Fail — so if the webhook pod is unhealthy, creating or updating those resources will be rejected. Always confirm webhook is running fine before debugging “my function won’t create” problems.

Step 2: Inspect pods and logs

Fission runs entirely as Kubernetes workloads, so kubectl is your primary diagnostic tool. By default the control-plane components live in the fission namespace.

Core components

Every core component should stay in the Running state with a stable restart count. If a pod is not Running, or its RESTARTS count keeps climbing, start with describe — the Events section surfaces the most common problems (bad image name, failed scheduling, failing readiness probe):

$ kubectl -n fission get pods
$ kubectl -n fission describe pod <pod>

If Events is not informative, read the component log:

$ kubectl -n fission logs -f <pod>

Each component owns a distinct part of the request lifecycle, so the component whose log matters depends on the symptom:

Function pods

A function pod runs two containers: fetcher and the runtime container. The fetcher container pulls your function code into the pod during specialization, and the runtime container is the language environment that executes your function.

Filter for the pods backing a specific function:

$ kubectl -n fission get pod -l functionName=<fn-name>

You can narrow the selection further with these labels:

To list only running pods, add a field selector:

$ kubectl -n fission get pod -l functionName=<fn-name> \
    --field-selector status.phase=Running

Then describe the pod and read each container’s log:

$ kubectl -n fission describe pod <pod>
$ kubectl -n fission logs <pod> -c fetcher
$ kubectl -n fission logs <pod> -c <runtime-container>

Builder pods

A builder pod compiles your source package into a deployable archive. Your function will not serve until the package it uses reaches the succeeded build status. Package build status is one of pending, running, succeeded, failed, or none.

Create a source package and watch its status:

$ fission pkg create --env go --src go.zip
Package 'go-zip-5obh' created

$ fission pkg list
NAME          BUILD_STATUS ENV
go-zip-5obh   running      go

If the build fails, the build logs are stored on the package and surfaced by fission pkg info:

$ fission pkg info --name <pkg-name>

To go straight to the builder pod logs, select by the environment name:

$ kubectl -n fission get pod -l envName=<env-name>
$ kubectl -n fission describe pod <pod>
$ kubectl -n fission logs <pod> -c builder

Step 3: Capture a support dump

If the steps above do not resolve the problem, capture a support dump and share it. The dump collects the Kubernetes specs and logs for the Fission components, builder, and function pods, plus the Fission CRDs (functions, packages, environments, and all trigger types), into a single archive:

$ fission support dump

By default the archive is written to a fission-dump directory. Use --output to choose a different directory and --nozip to write individual files instead of a single zip:

$ fission support dump --output ./my-dump --nozip

Open an issue on GitHub and attach the dump so others can help.

Symptom-to-first-place-to-look

Use this table to jump straight to the component or command most likely to reveal the cause.

Related

• Troubleshoot your Fission setup
• Troubleshoot your Kubernetes cluster
• fission check reference
• fission support dump reference