Keycloak Deprecated Options Warning: Find and Replace Them. The Keycloak deprecated options warning names each option at startup. Find it in keycloak.conf, kc.sh arguments or KC_ variables, swap it and restart.
Keycloak names the deprecated options you use in a WARNING block when it starts, often with the replacement. To clear it, find where each option is set (conf/keycloak.conf, kc.sh arguments or KC_ environment variables), swap in the replacement from the warning or the upgrading guide, then restart and check that the warning is gone.
Key takeaways
- The startup warning names each deprecated option it finds, often with its replacement.
- An option can be set on the command line, in the environment or in
keycloak.conf, andshow-configreports which source won.- A pass needs a server that started, logs you could read, and no warning in them.
This post is written against Keycloak 26.8.2, and other 26.x releases may differ. It starts from the exact messages, shows how to trace each flagged option to the place that sets it, and gives an old-to-new table you can work through. We captured the output below by starting a throwaway Keycloak 26.4.7 server on a local development database, with deprecated options set on purpose, and we compared the main messages with the 26.8.2 source code. Where we only read the code or the docs and did not run the option, the text says so.
What does the Keycloak deprecated options warning look like?
This is the main warning as our 26.4.7 server printed it, with five deprecated settings in its environment. The 26.8.2 source builds the same message:
WARNING: The following used options or option values are DEPRECATED and will be removed or their behaviour changed in a future release:
- cache-stack=kubernetes: Use 'jdbc-ping' instead by leaving it unset.
- event-metrics-user-events=remove_totp: Use `remove_credential` instead of `remove_totp`, and `update_credential` instead of `update_totp` and `update_password`.
- http-accept-non-normalized-paths
- tls-hostname-verifier=WILDCARD: STRICT and WILDCARD have been deprecated, use DEFAULT instead.
- legacy-observability-interface
Consult the Release Notes for details.
Each entry gives the option’s dashed name, adds the value when only certain values are deprecated, and adds a note when Keycloak has one. An entry can also be just the name, as two of these are, so you may still need the tables in Step 3. That test server stopped later in its start because the kubernetes cache stack needs a DNS query setting we did not give it, which has nothing to do with the warning. In 26.8.2, the code that builds each entry also adds the new option after the word Use when there is one, and the note on tracing-service-name names telemetry-service-name that way.
In our output these lines had no timestamp or log level, while ordinary log lines did, because the command line tool’s warn method writes them to its standard output rather than through a logger. A log file or a filtered log view may therefore leave them out, so check the console or container output as well. Our start-dev run rebuilt the server before starting it and printed each block twice, so seeing a name twice does not mean that two places set it.
Five other startup messages look similar and need a different fix. Our 26.4.7 server printed all of them except the Deprecated features line, which we quote from the 26.8.2 source and did not reproduce:
| Message | What it means | Fix |
|---|---|---|
Hostname v1 options [hostname-url, proxy] are still in use, please review your configuration (source) |
The code warns when a removed option from its list is set; these options have been removed | Use the first table in Step 3 |
KC-SERVICES0110: Environment variable 'KEYCLOAK_ADMIN' is deprecated, use 'KC_BOOTSTRAP_ADMIN_USERNAME' instead (source) |
The upgrading guide says the old admin variables have been deprecated, and the 26.8.2 code still falls back to them | Rename the variables |
Deprecated features enabled: multi-site:v1 (source) |
A feature that the code marks as deprecated is on, which is separate from any option | Look the feature up in the upgrading guide and change your features setting |
The following SPI options are using the legacy format and are not being treated as build time options. Please use the new format with the appropriate -- separators to resolve this ambiguity: kc.spi-email-template-provider (source) |
An option for a provider (a plug-in behind one of Keycloak’s extension interfaces, called SPIs) uses the older format, so Keycloak does not treat it as a build-time option | Rewrite it with -- separators, for example spi-email-template--provider |
The following used run time options are UNAVAILABLE and will be ignored during build time: followed by cache-stack: Available only when 'cache' type is set to 'ispn'. |
The option does not apply to the rest of your configuration, which is separate from any deprecation | Follow the note, or delete the option if you do not need it |
How to fix it in four steps
The whole job is a loop over the option names in the warning: read each name, find what sets it, replace it and restart.
Startup prints a warning that names the option (1), you check the three places it can be set (2) and find it (3), you replace it (4), and the next restart prints no warning (5).
Step 1: Copy the option names from the warning
Take the output from the most recent start and copy every name in the warning into a list. The warning shows the dashed form of the name, such as tls-hostname-verifier, followed by = and the value when only a value is deprecated. You can get the matching environment variable by uppercasing the name, changing dashes to underscores and adding KC_ (the formats are described here), which gives you KC_TLS_HOSTNAME_VERIFIER.
Step 2: Find where each option is set
Keycloak can read options from command line parameters, environment variables, conf/keycloak.conf (or a file you name yourself) and a Java KeyStore. The configuration guide lists these sources in that order and says that when an option is set in more than one of them, the one that comes first in the list determines the value. That matters when you clean up, because removing a line from keycloak.conf may change nothing if another source, such as a KC_ variable, also sets the option.
The quickest way to see the winning source is to ask Keycloak. The show-config command prints each option with its source in parentheses, such as ENV, keycloak.conf, CLI or Persisted (the source names):
bin/kc.sh show-config | grep -E 'cache-stack|tls-hostname-verifier'
# Our test server, with one option in the environment and one in keycloak.conf:
# kc.cache-stack = kubernetes (ENV)
# kc.tls-hostname-verifier = STRICT (keycloak.conf)
# In a running container, the same command through Compose or Kubernetes:
docker compose exec keycloak /opt/keycloak/bin/kc.sh show-config | grep tls-hostname-verifier
kubectl exec keycloak-0 -- /opt/keycloak/bin/kc.sh show-config | grep tls-hostname-verifier
Persisted marks a value saved by kc.sh build (after a build, our server showed kc.db = dev-file (Persisted)), so look in your image build rather than your runtime settings.
When you run show-config this way it is a separate command from the server, so do not count on it to include arguments you passed to the server’s own start command. It also names the kind of source rather than the deployment file that set the value, so search your deployment files as well, using grep -l, which prints only file names:
# Files you control: conf, Compose, Dockerfile, manifests.
# -l prints file names only, so secret values stay off your screen.
grep -rlE 'tls-hostname-verifier|KC_TLS_HOSTNAME_VERIFIER' conf/ compose.yaml .env Dockerfile k8s/
# A running Kubernetes pod: its start arguments, which can include values, then its variable names:
kubectl get pod keycloak-0 -o jsonpath='{.spec.containers[0].args}'
kubectl get pod keycloak-0 -o jsonpath='{.spec.containers[0].env[*].name}'
If you run the Keycloak Operator, also check additionalOptions in the Keycloak custom resource, which accepts any available option as a key-value pair under its dashed name. The operator has its own deprecations too: the tracing.serviceName and tracing.resourceAttributes fields of that resource are deprecated.
Step 3: Replace each option
Start with the removed options, because they no longer exist in your version. The upgrading guide says that “the deprecated proxy option was removed” (Proxy option removed) and that “the deprecated hostname v1 feature was removed” (Hostname v1 feature removed). On our 26.4.7 server, setting any option in the table below in the environment printed the Hostname v1 options warning, and kc.sh start-dev --proxy=edge stopped with this error instead:
Unknown option: '--proxy'
Possible solutions: --proxy-headers, --proxy-protocol-enabled, --proxy-trusted-addresses
| Removed option | Use instead | Source |
|---|---|---|
proxy=edge |
proxy-headers=xforwarded (or forwarded) and http-enabled=true |
Upgrading guide, 24.0 |
proxy=reencrypt |
proxy-headers=xforwarded (or forwarded) |
Upgrading guide, 24.0 |
proxy=none |
Delete the option | Upgrading guide, 24.0 |
proxy=passthrough |
The 24.0 table maps it to hostname-port, which has since been removed, so delete the option and put any fixed port in the hostname URL |
Upgrading guide, 24.0, 25.0 |
hostname-url, hostname-path, hostname-port |
One hostname value with the full URL, such as hostname=https://auth.example.com:8443/auth |
Upgrading guide, 25.0 |
hostname-admin-url |
hostname-admin with a full URL, because it no longer accepts a bare hostname |
Upgrading guide, 25.0 |
hostname-strict-https |
Delete the option, and put https:// in the hostname URL |
Upgrading guide, 25.0 |
hostname-strict-backchannel=true |
hostname-backchannel-dynamic=false, which is the default |
Upgrading guide, 25.0 |
Be careful when you swap proxy for proxy-headers. The guide warns that your reverse proxy must set and overwrite the header you choose, because a misconfiguration leaves Keycloak exposed, and the reverse proxy guide repeats that the proxy should overwrite these headers and not just append to them. For the proxy side of this change, see our guide to running Keycloak behind a reverse proxy.
The next table holds options that are deprecated rather than removed. As the warning above says, these will be removed or their behaviour changed in a future release, so plan the changes before your next upgrade. Our 26.4.7 run warned about each row except the two tracing- options, which the upgrading guide says “are now deprecated in favor of telemetry-service-name and telemetry-resource-attributes”, so those two rows rest on the guide and the source:
| Deprecated option or value | Use instead | Source |
|---|---|---|
KEYCLOAK_ADMIN, KEYCLOAK_ADMIN_PASSWORD |
KC_BOOTSTRAP_ADMIN_USERNAME, KC_BOOTSTRAP_ADMIN_PASSWORD |
Upgrading guide, “have been deprecated”, 26.8.2 source |
tracing-service-name |
telemetry-service-name |
Upgrading guide, 26.8.2 source |
tracing-resource-attributes |
telemetry-resource-attributes |
Upgrading guide, 26.8.2 source |
cache-stack=tcp, udp, jdbc-ping-udp, azure, ec2, google, kubernetes |
Leave cache-stack unset to get jdbc-ping |
All configuration, upgrading guide, 26.3 |
tls-hostname-verifier=STRICT or WILDCARD |
tls-hostname-verifier=DEFAULT, which is the default |
Upgrading guide, 25.0 |
event-metrics-user-events with remove_totp, update_totp or update_password |
remove_credential and update_credential |
All configuration |
legacy-observability-interface |
No replacement: the guide recommends not using it, and /health and /metrics are on the management port, 9000 |
Upgrading guide, 25.0 |
http-accept-non-normalized-paths |
No replacement is named, and the option’s description recommends leaving it disabled, so plan to remove it after checking that your clients send normalized paths | All configuration |
These tables are a selection, not a full list of the deprecated options in Keycloak. If your own warning names something that is not here, look it up in the upgrading guide.
Here is what the change looks like in a Compose file. For more on running it this way, see our production Docker Compose guide, and our Docker Compose generator can write a new file for you to compare against.
services:
keycloak:
image: quay.io/keycloak/keycloak:26.8.2
command: start
environment:
# Before:
# KEYCLOAK_ADMIN: admin
# KEYCLOAK_ADMIN_PASSWORD: ${KC_ADMIN_PASSWORD}
# KC_PROXY: edge
# KC_HOSTNAME_URL: https://auth.example.com
KC_BOOTSTRAP_ADMIN_USERNAME: admin
KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_ADMIN_PASSWORD}
KC_PROXY_HEADERS: xforwarded
KC_HTTP_ENABLED: "true"
KC_HOSTNAME: https://auth.example.com
We tested the new settings as plain environment variables with kc.sh start on the 26.4.7 server, not in Compose: the server started, printed none of the messages in this post, and its hostname debug page showed https://auth.example.com as the frontend URL.
Step 4: Restart and confirm the warning is gone
Restart Keycloak so it reads the new values, then search the output of that start. Recreate a container rather than restarting it, because docker compose restart does not pick up changes to your Compose file. On Kubernetes, apply the edited manifest first, and wait for kubectl rollout status to finish so that you read the new pod and not the previous one. Give the server time to finish starting before you save its output.
# Docker Compose: recreate the container, then save the output of this start.
docker compose up -d --force-recreate keycloak
docker compose logs keycloak > keycloak-start.log
# Kubernetes: apply the change, wait for the new pods, then save the output.
# If the manifest itself did not change, run kubectl rollout restart statefulset/keycloak instead of apply.
kubectl apply -f k8s/keycloak.yaml
kubectl rollout status statefulset/keycloak --timeout=5m
kubectl logs keycloak-0 > keycloak-start.log
# Either way: first look for the startup line, then for the warnings.
grep 'started in' keycloak-start.log
# Keycloak 26.4.7 on JVM (powered by Quarkus 3.27.1) started in 4.241s. Listening on: ...
grep -iE 'deprecated|Hostname v1|legacy format' keycloak-start.log
Count this as a pass only if the log command succeeded, the first search finds the startup line and the second prints nothing. That second grep exits with status 1 when it finds nothing, which is the result you want here, and you need the first two checks because a log command that failed or a server that never started also leaves it empty. Then test the things the option controlled: for proxy and hostname changes, load the login page and the admin console through your public address and confirm the redirects stay on it. Turning on hostname-debug=true gives you a page at /realms/master/hostname-debug that shows the URLs Keycloak resolved, and you can turn it off again afterwards. While you have the configuration open, our production-ready checklist and our list of default configurations to adjust are worth a pass.
Troubleshooting
The warning is still there after you removed the line. Another source may still be setting the option, such as a KC_ variable from a .env file or a manifest. Run show-config again and read the source in parentheses.
Hostname v1 options [proxy] appears, but you did not think proxy was a hostname option. In the 26.8.2 source, the removed proxy option is in the same list as the hostname options, so the message covers both. Replace it with proxy-headers as in Step 3.
Redirects break after moving to hostname v2. HTTPS is no longer enforced unless it is part of the URL, and a port left out of the URL comes from the request headers. Set hostname to the full public URL and check that your proxy sends the headers you named in proxy-headers.
The server stops with Unknown option: '--proxy'. The option was removed and is still on your start command. Check the command or args of your container, then replace it as in Step 3.
The cluster, without the on-call
Skycloak runs real upstream Keycloak in the region you choose, and takes the upgrades, backups, certificate rotation and patching off your team. No fork, so you can export and self-host whenever you want.
How does this work on a Skycloak managed cluster?
On a Skycloak cluster, you can read your cluster’s server logs in the Logs Viewer, which covers startup and shutdown under its system logs.
The cluster Edit page covers settings such as size, version and HTTP relative path. For a warning about an option you cannot see there, report it from the dashboard with the option name and the Keycloak version, since the docs send specialized configurations not available in the dashboard to our support team.
If you are planning an upgrade, the cluster versions API shows the upgrade path and the breaking changes between two versions. Auto-upgrade never applies a version that is a major change or carries a breaking change: it waits for you.
FAQ
Do I have to fix Keycloak deprecated options warnings right away?
The deprecation message is a warning rather than an error, but it does say the option will be removed or its behaviour changed in a future release, so fix it before your next upgrade. A removed option needs fixing now, because it no longer exists in your version.
Why do I see the KEYCLOAK_ADMIN warning on some starts and not others?
We saw this on our test server: the first start on an empty database printed the warning, and the next start on the same database, with the variables still set, did not. In the 26.8.2 code, the warning comes from the step that reads those variables, which runs only on a new install. Rename them anyway, so the next fresh environment is clean.
Does renaming KEYCLOAK_ADMIN change my existing admin user?
It should not. The bootstrap admin and recovery guide says these temporary accounts are created only during the initial start, when the master realm does not exist yet, so renaming the variables has nothing to act on later. The same guide covers what to do if you are locked out.
Where is the full list of Keycloak deprecated options?
All configuration marks deprecated options and values on the current version, and the help text puts DEPRECATED. in front of those options’ descriptions too, as kc.sh start --help-all did on our server, so it is worth checking on the version you have installed. The upgrading guide explains each change, version by version.
What to do next
Check the output of your latest start, copy the names from the warning, replace each one using the tables above, and restart to confirm the warning is gone. If you would rather not track server options across Keycloak versions yourself, Skycloak managed Keycloak hosting runs your Keycloak cluster for you, and its cluster Edit page covers settings such as the Keycloak version.
Sources
- Keycloak, “All configuration”, retrieved 2026-11-05, https://www.keycloak.org/server/all-config
- Keycloak, “Configuring Keycloak”, retrieved 2026-11-05, https://www.keycloak.org/server/configuration
- Keycloak, “Upgrading Guide”, retrieved 2026-11-05, https://www.keycloak.org/docs/latest/upgrading/index.html
- Keycloak, “Configuring the hostname (v2)”, retrieved 2026-11-05, https://www.keycloak.org/server/hostname
- Keycloak, “Configuring a reverse proxy”, retrieved 2026-11-05, https://www.keycloak.org/server/reverseproxy
- Keycloak, “Configuring providers”, retrieved 2026-11-05, https://www.keycloak.org/server/configuration-provider
- Keycloak, “Bootstrapping and recovering an admin account”, retrieved 2026-11-05, https://www.keycloak.org/server/bootstrap-admin-recovery
- Keycloak, “Advanced configuration” (Operator), retrieved 2026-11-05, https://www.keycloak.org/operator/advanced-configuration
- Keycloak, release 26.4.7, retrieved 2026-11-05, https://github.com/keycloak/keycloak/releases/tag/26.4.7
- Keycloak, source code at tag 26.8.2, retrieved 2026-11-05, https://github.com/keycloak/keycloak/tree/26.8.2
- Docker, “docker compose restart”, retrieved 2026-11-05, https://docs.docker.com/reference/cli/docker/compose/restart/
- Kubernetes, “kubectl rollout status”, retrieved 2026-11-05, https://kubernetes.io/docs/reference/kubectl/generated/kubectl_rollout/kubectl_rollout_status/
- GNU, “GNU Grep Manual”, retrieved 2026-11-05, https://www.gnu.org/software/grep/manual/grep.html


