Troubleshooting and FAQ
Start with the exit code: every way an Executor binary ends has its own. The table below says what each one means and where to look.
What an exit code tells you
| Exit code | Cause | What to check |
|---|---|---|
| The guest's own code | The application exited by itself. | Your application's logs. The Executor passes the code on unchanged. |
0 | A checkpoint stop. | Expected when your application reports its completion checkpoint. |
69 | Required enforcement is unavailable: a strict cap or a container_fallback: "strict" sandbox primitive cannot be enforced on this host. The guest never started. | See The binary refuses to start with 69. |
70 | A quota or policy violation: the guest exceeded a strict memory cap or the PID quota, or triggered a fatal syscall trap. | Raise the cap in a new build, or check the syscall_profile. |
75 | The exit-event lease was lost under FAIL_CLOSED. | Reachability of the control API, credentials, TLS pinning, and max_consecutive_failures. |
76 | A utilization exit event matched. | The rule's metric, threshold and for window. |
78 | The pre-launch gate blocked startup: the stop tag was already active. | Your control API's response; check_before_start: true polls before launch. |
124 | A time-based exit event: duration, cron, timestamp or idle. | Expected at the configured time. |
143 | An external or message exit event matched, or an operator ran oee stop. | The audit event names the rule. |
The codes of planned stops can be changed in stop_policy.exit_codes; see Stopping and exit codes.
The binary refuses to start with 69
A strict cap must be held by a kernel-enforced limit before the guest starts; the Executor never silently downgrades it.
- Linux without a writable cgroup. The Executor needs a delegated cgroup v2 subtree, a transient scope from your user's
systemdmanager, or a writable container cgroup. Provide one, or setresources.allow_governor_fallback: truein a new build to accept the supervisor governor. - A container that blocks namespaces. With
sandbox.container_fallback: "strict", a missing namespace primitive stops the launch. Use"auto"to layer Landlock,seccomp-BPF, subreaper containment andsetrlimitinstead. - The startup audit event always names the enforcement tier the Executor selected.
The binary refuses to start: verification failed
Any byte change to the supervisor, the policy or the runtime fails BLAKE3 and Ed25519 verification, and the guest never starts. Rebuild and re-sign with oee build, and check a binary with oee inspect <binary> --verify-key oee.pub.
A sandboxed application cannot read a file
Paths outside read_only_paths and read_write_paths are rejected by the kernel with EACCES or ERROR_ACCESS_DENIED. Add the path to the right list and rebuild. Files the application must write go in read_write_paths; they persist after the application stops.
A sandboxed application cannot reach the network
Check sandbox.network.outbound_allow and outbound_allow_cidrs, and inbound_allow_ports for listening ports. Exit-event polling is not affected: the supervisor polls from its own network context.
A JIT runtime crashes under the sandbox
Python, JVM and Node.js need the runtime-managed syscall profile, which keeps the memory protection transitions a JIT needs. It is selected automatically for those runtimes; check that the manifest does not force strict.
The application is slower than expected
A strict CPU cap throttles the whole tree to its limit in every enforcement period. Check the resolved caps with oee status. A percentage cap resolves against the machine or the container the binary runs in, once, at startup.
An exit event never fires
- Run
oee statusto see the status of the last exit-event poll. - With
FAIL_OPEN, transient errors are only logged; useFAIL_CLOSEDwithmax_consecutive_failuresif a lost control plane must stop the application. - Check the
stop_whenconditions andmatch(ANYorALL), and the top-levelcombinator. - With
combinator: "ALL", every rule must match before the application stops. - Validate JSONPath expressions and cron schedules with
oee validate --strict.
Workers survive a stop
They do not: the Executor stops the whole process tree, including workers that double-fork or call setsid, through the cgroup, the PID namespace or the Job Object. If a process outlives the stop, check that it was started outside the binary.
Replicas do not scale out
- Auto-scaling needs a cap on every metric it uses.
- Usage must stay above an upper threshold for the whole
scale_out_afterwindow, and acooldownfollows each action. max_replicasandautoscale.total_limitsbound the count.- A replica that fails its readiness check within the timeout counts as a failed start.
Frequently asked questions
Is the Executor available?
The Executor is in early preview — message us for access, and OpenEng sends you the build by email; Install lists the platforms.
Do I have to change my application?
No. Exit events, caps, the sandbox and scaling all run in the supervisor, outside your code. Checkpoints are optional, for applications that want to report their own progress.
Does stopping delete anything?
No. A stop ends execution; the binary, the runtime cache, the logs and every file your application wrote remain on disk.
Can an operator raise a strict cap on a running instance?
No. Environment variables, CLI arguments, the control socket and remote responses cannot raise or disable a strict cap. Changing it requires a new signed build.
Does the Executor need root, Docker or Kubernetes?
No. Sandboxing uses unprivileged kernel primitives, capping uses a delegated cgroup or a Job Object, and scaling runs inside the supervisor. The Executor also runs as PID 1 in containers; see Containers and Kubernetes.
Which languages does the Executor support?
Native binaries (Go, Rust, C, C++), Python 3.10 to 3.13, Java and Kotlin on JVM 17, 21 and 25, and Node.js, Deno and Bun. See Runtimes and adapters.
How large is the overhead?
The design targets are less than 3.0 MB for the core supervisor and less than 6.0 MB for extended, less than 15 ms of warm startup overhead, and less than 6 MB of RSS at one-minute polling. These are targets, not measured results; see Performance specifications.
Can I try a policy without building?
Yes. oee run -f oee.yaml -- <cmd> runs any local command under the sandbox and exit events.