Skip to content

Errors and what to do

Every refusal field encryption can give at startup, in a request or in a command, what it means and what to change.

Startup refusals name the file, the field and what to do; all problems of a config are reported at once.

At startup

You seeIt meansDo
…: names the key HEALTH, which does not existA field names a key that was never createdbackd-server secret create --realm r --type key --generate --name HEALTH, and save the key; or --value to restore a key you hold
…names HEALTH, which is a plain secret, not a keyThe name belongs to an ordinary secretUse another name, or delete the secret if nothing uses it
fields are declared encrypted … but the realm has no authEncrypted fields need somewhere to keep keysEnable auth in realm.yaml
fields.x: field "x" is not declared in schema.jsonThe path isn’t a field of the collectionDeclare it, or fix the path
…encrypt.key: name the key secret …key is missing or malformedUpper-case letters, digits and _, starting with a letter
…encrypt.search: "…" is not a kind of searchOnly equality existsUse search: equality
…encrypt.normalize: normalization applies to the blind index / …"x" is not a normalizationnormalize without search, or an unknown stepAdd search: equality; steps are trim, lower, upper
…encrypt.unique: a unique encrypted field needs search: equalityThe blind index is what is uniqueAdd search: equality
system fields (id, _meta) can't be encryptedThose are backd’sEncrypt a field of your own
a field inside an array can't be encryptedAn element has no stable pathEncrypt the array as a whole
a date field (x-backd-store: date) can't be encryptedA date is stored as a date, not textStore it as a string, or leave it plain
x is already encrypted as a wholeAn object and its partsEncrypt one of them
x is the source of the reference …Expanding a reference needs the plain valueReference a plain field
x is a file fieldFile contents rely on bucket encryptionLeave file fields out
x is in an index of indexes.json / …in the text indexAn index can’t see inside an encrypted valueUse search: equality (and unique) instead of an index
x is a replace / pull / unset target of on_owner_deleteThose edit values inside the databaseUse remove
x is grouped or measured by aggregateThe database can’t compute over encrypted valuesAggregate a plain field
read rules: document.x is encrypted without search: equalityA read rule is applied inside the database queryAdd search: equality and compare with == or in, or move the condition to reveal
read rules: document.x is encrypted with a blind index, which only answers == and in!=, ranges and the rest can’t use an index of hashesUse == or in
…reveal: unknown field document.y / `data` is only available on create and update / role "z" is not declaredA reveal rule is checked like any ruleFix the expression; it sees document, user, now, the helpers and appConfig

In a request

You seeIt meansDo
400 field_encrypted on a where or order_byThe field is encrypted: only =/$in on a field with search: equality work, and never nullFilter on another field, or enable search
500 “an encrypted field can’t be read or written: its key is not available”The key is missing or the instance has no secrets master keyLook at the server log (it names the field, never the value); restore the key with backd-server secret create --value … and check BACKD_SECRETS_KEY
A value comes back null and _meta.redacted lists itIts reveal rule said no for this callerIntended; change the rule or the caller’s roles
409 on a write naming the fieldA unique: true field already holds that valueChoose another value

In a command

You seeIt meansDo
409 creating a keyA secret with that name existsAnother name; --skip-existing in scripts
409 deleting a key: “still used by …”A field names it, or data keys that encrypted values depend on are wrapped by itChange the configuration and backd encrypt migrate until status is complete
409 a rotation of this key is unfinishedA rotation stopped half waybackd secret rotate --resume
409 a migration of this collection is already runningOne job per collectionWait, or cancel it
the key given for … has the fingerprint …, but … is encrypted with the key …Wrong key for an export or import --fieldUse the key whose fingerprint the manifest records
422 import_refused naming encrypted fieldsNobody here can open themGive the source keys with --field; the dry run lists them
Edit this page · Last updated 13 Nov 2026