Skip to content
Documentation
Development documentation
This describes Keydra as it is being built and is not a released version. What it documents can change before a release.

Troubleshooting

The failures Keydra actually produces, what each of them means, and what to do about it.

A target will not connect#

The row stays Down, or Test connection fails.

Procedure

  1. Check that Keydra can reach the address at all. It is Keydra that connects, not your browser — an address that works from your laptop may not work from the container.

  2. If the target is on a private network, give the profile a tunnel — see Reaching targets through a jump host.

  3. Check the credentials. A target that requires a password and is given none refuses at authentication rather than at connection, which looks the same from the outside.

  4. If the target speaks TLS, tick Use TLS. If it presents a certificate signed by a private authority, that authority has to be in the truststore of the machine Keydra runs on — Keydra trusts the system store and has no setting of its own.

  5. For a Sentinel profile, check the Sentinel master name. Keydra asks Sentinel where that master is; a name Sentinel does not know produces no address.

Verification

Test connection reports success against what the form currently says, without saving anything.

Nobody can sign in#

Procedure
If the sign-in form refuses a password you believe is right

Check whether the message is Wrong username or password. or Too many sign-in attempts. The second is the throttle; wait a few minutes. See Sign-in protection.

If a provider button sends you to the provider and the provider refuses

Almost always the redirect URI. Copy it from the provider’s form in Access → Sign-in exactly as it appears, including the provider key, and register that at the provider.

If the provider accepts you and Keydra then shows nothing

The account exists and holds no grants. An account lets somebody sign in and see nothing. Grant a role — see Granting access.

If the redirect comes back to the wrong host

Set KEYDRA_PUBLIC_URL, and KEYDRA_BEHIND_PROXY with KEYDRA_TRUSTED_PROXIES if there is a reverse proxy in front.

If every page says Security off

KEYDRA_SECURITY_ENABLED is false. Everyone who can reach the instance can do everything. See Configuring authentication before exposing Keydra.

A schedule did not run, or an alert did not arrive#

Procedure
If a schedule did not run

  1. Check About on each instance. Only the one holding the leader’s work registers schedules; if none holds it, none of them is registered.

  2. Check the schedule is enabled, and look at its run history. A run is recorded before it starts, so a job that never finished appears as one that never finished rather than as one that never ran.

  3. Check the permission. A schedule requires the permission its job would need by hand, and that is checked again when it runs — a grant revoked since it was written turns it into a refused run rather than a silent one.

If a rule never fires

  1. Check it is enabled. Only an enabled rule keeps its target sampled.

  2. Check Has to hold for. A condition that never holds that long never leaves pending.

  3. If the rule compares with a historical window, check that the readings store is configured and holds that far back. A rule whose baseline cannot be read is left exactly as it is — not fired, not cleared.

If a rule fires and nothing arrives

  1. Look at the event in History. Delivery is recorded on it, including a failure and its reason.

  2. Check the delivery’s credential. It is never returned by the API, so a form saved with an empty token kept the old one — or never had one.

Keys and values behave unexpectedly#

Procedure
The key list stops before the end

The page says Limit reached — it holds as many keys as it safely can. Narrow the filter to see different ones. This is a limit on what is drawn, not on what exists.

A value shows only its beginning

It is marked Shown in part. It is too large to return whole, and editing or copying from there would overwrite the rest with something shorter. Read it through the API or an export instead.

A value looks like nonsense

Change Encoding from Automatic to the one it actually is. Automatic detection is a guess, and one format in particular — Brotli — announces itself in no way at all.

A key that was in the list is gone when opened

The panel says This key no longer exists — it expired or was deleted after the list was built. A SCAN is a walk over a live keyspace, not a snapshot of one.

A command is refused in the console

See Why some commands are refused. The refusal names the reason, and the list is configuration.

Deployment problems#

Procedure
The application will not start

  • Check KEYDRA_DB_URL, KEYDRA_DB_USERNAME and KEYDRA_DB_PASSWORD. There is no in-memory fallback: Keydra runs against PostgreSQL and nothing else.

  • Check KEYDRA_SECRET_KEY is set. Without it there is nothing to decrypt stored credentials with.

Stored credentials stopped decrypting after a deployment

KEYDRA_SECRET_KEY changed and the old key is not in KEYDRA_PREVIOUS_SECRET_KEYS. Put it back, and follow Rotating the instance key properly.

The interface loads but every request is refused

Check whether you are signed in. Asking whether you are is open to anybody, so a 401 on that question means a cookie was presented and rejected — usually an ended session, revoked from another browser.

Changes made on one instance do not reach a browser on another

KEYDRA_STORE_URL is not set, or the instances point at different stores. Without a shared store, the notification hub fans out to local sockets only.

A backup destination test fails against MinIO or another S3-compatible store

Tick Address the bucket by path. Without it, a MinIO on an IP address is looked up as bucket.10.0.0.4, and the failure reads as a DNS problem.

An outbound address is refused

Link-local addresses are refused and there is no setting to allow them. 169.254.169.254 answers with the machine’s cloud credentials.

Edit this page