What Onebox refuses

Onebox refuses declarations it cannot honour.

Every refusal below follows from it. The full list is the error code catalogue, generated from the binary: validation codes raised while the project file is read, operation codes raised while a command runs, and the lifecycle failure contract.

The ones most likely to surprise you

strategy_ungated: asking for strategy: rolling without a health check. A rolling release stands the newcomer up and waits for it to report healthy; with nothing to wait for, “rolling” would silently mean “recreate with extra steps”. So it is refused.

schedule_untranslatable: a cron expression whose meaning the host’s scheduler cannot preserve. See exact cron translation.

unknown_service_driver: a driver outside the closed set of eleven. See the driver catalogue.

connection_variable_claimed: an authored value claiming a name a managed-service connection supplies. See connection-variable validation.

route_collision: two workloads claiming the same entrypoint, protocol, hostname and path. The proxy would accept both and route to one, and nothing would say which.

stateful_replicas: a workload keeping durable state asking for more than one replica.

override_not_permitted: an environment override touching anything outside the permitted set. An environment may override exactly replicas, resources, env, envFiles, strategy and routes; everything else, image and command and volumes among them, is refused. It is an allow-list of fields that can differ while this is still the same application; a staging environment with a different image is a different application under the same name.

service_settings_unsupported: a setting declared for a driver with no mechanism to read it. Silently ignoring it would leave you believing it applied.

A rolling workload publishing a host port: two replicas cannot both hold 8080 on the host, so the roll would either fail halfway or quietly become a recreate. Either give the workload strategy: recreate, or drop publishedPorts and route to it through the proxy. This one arrives as a plain project_invalid today, with no dedicated code.

host_owner_mismatch: a second application trying to mutate a host that already belongs to one. Not a load-time refusal: it comes from the host itself, before anything changes. See the ownership boundary.

host_environment_mismatch: a second environment of the same application trying to mutate a host another environment claimed. Container and volume names carry the application, not the environment, so the two would not collide: the newcomer would adopt what is already there. See the ownership boundary.

Where a refusal is about safety, not tidiness

See the bounded safety guarantees and the recovery overrides.

A missing or invalid job result from a migration becomes changed=unknown and halts before workload replacement, unless a strong or break-glass local confirmation authorized that exact plan. An unknown result is treated as the dangerous case.

Refusals carry the way out

Every failure carries a typed code, the path that produced it, and where possible the line and the command that resolves it.

✗ ob: "replicaz" is not a field of this contract (line 10); did you mean "replicas"?
  at: workloads.web.replicaz
  code: unknown_field

The lifecycle failure contract goes further: each code carries one safe command classified as diagnostic, next, or resolving. It is validated to start with ob and to contain no credential material. An agent can branch on the code without mistaking a read-only inspection for a repair.

Stable error codes

See the error-code contract.