---
title: "What Onebox refuses"
summary: "Onebox refuses declarations it cannot honour. The pattern, the refusals most likely to surprise you, and why force cannot override them."
description: "The refusals worth knowing, and the principle behind all of them."
status: shipped
read_when:
  - "A command refused and the reason is not obvious"
  - "Deciding whether a refusal is a bug or a design decision"
---
> Onebox refuses declarations it cannot honour.

Every refusal below follows from it. The full list is the
[error code catalogue](/docs/reference/errors), 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](/docs/guides/cron-jobs#cron-is-translated-exactly-or-refused).

**`unknown_service_driver`**: a driver outside the closed set of eleven.
See the [driver catalogue](/docs/reference/drivers).

**`connection_variable_claimed`**: an authored value claiming a name a
managed-service connection supplies. See [connection-variable validation](/docs/guides/databases#reaching-a-pooler-or-a-read-replica).

**`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](/docs/concepts/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](/docs/concepts/ownership-boundary).

## Where a refusal is about safety, not tidiness

See the [bounded safety guarantees](/docs/reference/policies#safety-claims-are-bounded)
and the [recovery overrides](/docs/guides/rollback#when-recovery-refuses).

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](/docs/reference/errors).