General errors

Causes and remedies for the error codes that any operation can raise: missing objects, conflicts, sign-in and privileges.

`error.not_found`

Text in the console: The object was not found. It may have been removed. Refresh the inventory.
Meaning for API clients: The object does not exist (or is not visible to the caller).
Code: NOT_FOUND, HTTP 404

Cause. The object does not exist, or it is not visible to the caller. Kyvernon gives the same answer for both, so that a caller without access cannot find out whether an object exists. The object may have been removed, or the identifier is wrong.

Remedy.

Refresh the inventory in the console, or list the objects again: kyvernon inventory search <name>.
Check the identifier you used. Identifiers have the form <kind>-<number>.
When the object should exist, ask an administrator whether your role grants access to it: kyvernon privileges check <entity> <privilege>.

`error.already_exists`

Text in the console: An object with that name or id already exists. Choose another name.
Meaning for API clients: An object with that name or id exists.
Code: ALREADY_EXISTS, HTTP 409

Cause. An object with that name or identifier exists already, in the same folder or the same scope.

Remedy.

Choose another name.
To change the existing object, read it, then update it instead of creating it again.

`error.conflict`

Text in the console: The object changed while you were editing it. Reload the page and apply your change again.
Meaning for API clients: Compare-and-set failed: expectedVersion is stale.
Code: CONFLICT, HTTP 409

Cause. The object changed between the moment you read it and the moment you saved it. Every change names the version it is based on (expectedVersion in the API, If-Match for the firewall), and that version is no longer current.

Remedy.

Reload the object in the console, or read it again: kyvernon inventory get <id>.
Apply your change again to the version that you read. With the CLI, pass the new version: kyvernon inventory update <id> --expected-version <version> --body-file <file>.

`error.unauthenticated`

Text in the console: You are not signed in. Sign in and try again.
Meaning for API clients: No or invalid bearer token.
Code: UNAUTHENTICATED, HTTP 401

Cause. The request carries no bearer token, or the token is not valid: it has expired, was revoked, or belongs to a session that has ended.

Remedy.

Sign in again: kyvernon login <username> --save. In the console, use Sign in.
API clients check that the header Authorization: Bearer <token> is sent and that the API token has not expired: kyvernon auth api-tokens list.

`error.permission_denied`

Text in the console: The request was refused. Your role does not include the required privilege. Ask an administrator for access.
Meaning for API clients: The caller lacks a privilege on the entity.
Code: PERMISSION_DENIED, HTTP 403

Argument	What it holds
`privilege`	the privilege that the operation needs.

Cause. The user, or the token, holds a role without the privilege that the operation needs on that object. The privilege is named in the argument privilege of the API response.

Remedy.

Check the privilege in the response, then check what your role holds: kyvernon privileges check <entity> <privilege>.
Ask an administrator for a role that includes the privilege on that object. The administrator grants it with kyvernon permissions set <entity> <principal> --role <role>.
Pass on the message id, the name of the privilege and the time.

`error.audit_record_immutable`

Text in the console: Audit records cannot be deleted.
Meaning for API clients: Audit records cannot be deleted.
Code: PERMISSION_DENIED, HTTP 403

Cause. A request tried to delete an audit record. Audit records are append-only, and no role can delete them.

Remedy.

Do not delete audit records. Remove the request from the script or tool that sends it.
To limit how long audit records are kept, an administrator sets audit_age in the [retention] section of the controller configuration. Kyvernon removes records that are older than that itself.