First commands
info reports BTF, tracefs, tracepoint visibility, privilege, unprivileged BPF policy, and the selected database. It does not need root.
For collector diagnostics:
Recording failures
Insufficient privilege
unprivileged_bpf_disabled is 2, an unprivileged load must fail. That is expected.
Tracepoints unknown or unreadable
If tracefs isdrwx------ root root, info reports tracepoint availability as unknown rather than guessing. Run the recorder with privilege. Do not chmod tracefs to make an unprivileged check pass.
BPF object build failure
clangis installed.- libbpf headers and library are installed.
pkg-config --libs libbpfresolves.- The expected seven tracepoint sections are present.
BTF layout failure
Target command errors
The command after-- is executed directly, not through a shell.
-- is rejected.
Database failures
Database not found
--db value that was used for recording, or set SYSCALL_DB. The default is ~/.local/share/syscall/syscall.db.
Schema version unsupported
Read-only commands do not migrate. A database created by a newer schema is rejected explicitly, and a missing schema is not initialized during inspection. Use a compatible database or record a new session with the current collector. Do not editPRAGMA user_version to bypass the check.
Session not found
The session ID must match exactly. List available sessions:Unexpected capture results
No file or network rows
Check, in order:- Was the target in the selected scope?
- Did the target perform
openator IPv4/IPv6connect? - Is the activity inside the recording window?
- Did the session report filtered events, loss, or malformed samples?
- Did the target use
open,openat2,sendto,sendmsg, or another unhooked call?
Connect rows exist but do not show an established session
That is expected.network_connect.established is always false. The hook records connect attempts, not application-level sessions.
Failed connect to localhost
A refused connection to an unused local port is valid failed-connect evidence. It does not indicate a recorder bug.Ring-buffer loss or userspace drops
Inspect the counters:A session remains recording
The recorder likely crashed before finalization. Committed rows remain readable. Treat the session as incomplete and inspect the finalization error if one was recorded.
Verification failures
verify assessment codes:
If verification returns
unable_to_verify, read the finding codes. DB_SCHEMA_UNSUPPORTED means the schema is newer than the binary. A read or scan failure is not a clean result.
Do not repair or rewrite the database to make verification pass. Preserve the original evidence and document the failure.
Export failures
Output already exists
Export refuses replacement without confirmation:--force when replacing the file is intentional.
Destination directory missing
Create the directory first. Export creates the file atomically but does not create an arbitrary parent path.Export verification fails
Desktop failures
Missing WebKitGTK or GTK development packages
Install the desktop prerequisites. Without them, the Tauri GUI cannot compile; the headless service layer can still be tested.Wrong binary path
Afternpm run tauri:build -- --no-bundle from desktop/, the binary is at the workspace root:
Blank window under WSLg
Export button cannot choose a path
That is intentional. The backend fixes the export directory to~/.local/share/syscall/exports or SYSCALL_EXPORT_DIR at startup.
Documentation preview
Fromdocs/:
docs.json and the file has valid frontmatter.
Before asking for help
Collect:syscall info --json- The exact command and exit code
- The session status and counters
- Relevant
RUST_LOGoutput - Whether the host is WSL2, native Linux, or a container
- The database schema version