In plain terms: Keycloak is trying to connect to a MariaDB/MySQL database named keycloak, but that database doesn’t exist on the host/port you’ve configured—or the name is misspelled. As a result, the JDBC connection fails and Keycloak aborts startup. [1][2]

Why this happens (root cause)

• Missing schema: The keycloak database isn’t created yet, so the driver returns “Unknown database.” [1]
• Wrong connection target: You’re pointing to the wrong host, port, or service name (e.g., Docker network hostname mismatch), so you connect to a different server where the schema doesn’t exist.
• Typo or wrong driver/URL: A misspelled DB name or using jdbc:mysql:// while you configured KC_DB=mariadb can lead to confusion. Stick to jdbc:mariadb:// for MariaDB. [2]
• UNIX socket vs TCP mismatch: If MariaDB listens only on a UNIX socket but your JDBC URL assumes TCP (host:port), the connection will fail until you add the socket parameter.
• Insufficient privileges: The user can connect but lacks privileges on the keycloak schema; some setups will surface slightly different errors after initial connection.

Step 1: Navigate to the Configuration File

When you download and extract Keycloak (for example, version 26.3.4), you’ll find a folder structure like this:

keycloak-26.3.4/
   ├── bin/
   ├── conf/
   ├── lib/
   └── ...

Inside the conf folder, you’ll find a file named keycloak.conf.

This file is where Keycloak reads its database configuration details.

The path looks like this:

\keycloak-26.3.4\conf\keycloak.conf

Step 2: Open and Edit keycloak.conf

Open the keycloak.conf file in your preferred text editor (Notepad, VS Code, or any IDE).

Here, you can specify database details if you’re connecting to an external database (like PostgreSQL or MySQL). But if you’re just starting out and want Keycloak to automatically create its database, you don’t need to make changes. Keycloak will use the default configuration and set it up for you.

Step 3: Run the Start Command

Now, it’s time to launch Keycloak.

1. Open Command Prompt (CMD).
2. Navigate to the bin folder inside your Keycloak directory:

cd keycloak-26.3.4\bin

Run the following command:

./kc.sh start-dev

This tells Keycloak to start in development mode. In this mode, Keycloak automatically sets up the necessary database tables for you.

Step 4: Database Creation Happens Automatically

When you run the ./kc.sh start-dev command:

• Keycloak connects to the default database (by default, it uses an embedded H2 database).
• It automatically creates all required tables needed for users, roles, clients, sessions, and tokens.
• You don’t have to manually create the schema or run SQL scripts.

This makes it perfect for testing, learning, or experimenting with Keycloak.