docs: add comprehensive troubleshooting guide#94
docs: add comprehensive troubleshooting guide#94Kadiyam-LakshmiPrasanna wants to merge 5 commits into
Conversation
Signed-off-by: Kadiyam-LakshmiPrasanna <lakshmiprasannakadiyam25@gmail.com>
github-actions
Bot
added
level:beginner
btwshivam
left a comment
btwshivam
left a comment
There was a problem hiding this comment.
useful guide, accurate on kernel/btf/capabilities. two technical fixes inline before merge: the kprobe entry and the clang requirement.
| * **Error:** `/sys/kernel/btf not found` or `failed to load BPF program` | ||
| * **Cause:** Your current kernel version is likely older than 5.8 or lacks BPF Type Format (BTF) support. | ||
| * **Fix:** Ensure you are running a modern, managed Kubernetes distribution (EKS, GKE, AKS, etc.) or update your host kernel to 5.8+. | ||
| * **Error:** `failed to attach kprobe` |
There was a problem hiding this comment.
kerno uses tracepoints, not kprobes (it's the project's stated preference and every program under internal/bpf/c is tracepoint-based), so failed to attach kprobe isn't an error anyone hits here. the fix is also off: kerno is CO-RE (vmlinux.h + BTF), so runtime attach needs BTF, not linux-headers (headers only matter for compiling the bpf C with clang, which section 2 already touches). reframe this around tracepoint attach plus BTF, or drop it.
| If you are experiencing issues while setting up or running Kerno, please check the common scenarios below. | ||
|
|
||
| ## 1. Installation & Dependencies | ||
| * **Error:** `clang: command not found` or `llvm: command not found` |
There was a problem hiding this comment.
worth a one-liner that make build needs no clang, it uses bpf stubs. clang/llvm/libbpf are only for make build-ebpf. as written this reads like clang is required to set kerno up at all, which can scare off contributors who just want the stub build.
github-actions
Bot
added
level:intermediate
github-actions
Bot
added
level:intermediate
|
Hi @btwshivam, I have addressed the feedback regarding kernel/BTF troubleshooting and clarified the build dependencies. The PR is ready for your review and workflow approval. Thank you! |
|
fix ci its filing.. |
2 participants
What
This PR adds a
TROUBLESHOOTING.mdfile to the root directory. This guide provides a centralized, easy-to-read reference for common environment-related errors that new contributors frequently encounter when setting up Kerno.Why
Fixes #91.
Previously, contributors were hitting repetitive environment errors (e.g., missing BTF support, clang/LLVM dependencies, or permission issues) that clogged the issues section. This documentation empowers users to self-diagnose and resolve these common hurdles quickly.
Testing
Checklist
docs: subject).git commit -s).