{"id":3276,"date":"2025-10-01T05:23:53","date_gmt":"2025-10-01T05:23:53","guid":{"rendered":"https:\/\/www.devopssupport.in\/blog\/?p=3276"},"modified":"2025-10-01T05:23:54","modified_gmt":"2025-10-01T05:23:54","slug":"fixing-keycloak-unknown-database-keycloak-sqlstate-42000-error-1049-with-mariadb-mysql","status":"publish","type":"post","link":"https:\/\/www.devopssupport.in\/blog\/fixing-keycloak-unknown-database-keycloak-sqlstate-42000-error-1049-with-mariadb-mysql\/","title":{"rendered":"Fixing Keycloak \u201cUnknown database \u2018keycloak\u2019 (SQLSTATE 42000, Error 1049)\u201d with MariaDB\/MySQL"},"content":{"rendered":"\n<p>In plain terms: Keycloak is trying to connect to a MariaDB\/MySQL database named <code>keycloak<\/code>, but that database doesn\u2019t exist on the host\/port you\u2019ve configured\u2014or the name is misspelled. As a result, the JDBC connection fails and Keycloak aborts startup. [1][2]<\/p>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n\n<h2 class=\"wp-block-heading\">Why this happens (root cause)<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Missing schema<\/strong>: The <code>keycloak<\/code> database isn\u2019t created yet, so the driver returns \u201cUnknown database.\u201d [1]<\/li>\n\n\n\n<li><strong>Wrong connection target<\/strong>: You\u2019re 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\u2019t exist.<\/li>\n\n\n\n<li><strong>Typo or wrong driver\/URL<\/strong>: A misspelled DB name or using <code>jdbc:mysql:\/\/<\/code> while you configured <code>KC_DB=mariadb<\/code> can lead to confusion. Stick to <code>jdbc:mariadb:\/\/<\/code> for MariaDB. [2]<\/li>\n\n\n\n<li><strong>UNIX socket vs TCP mismatch<\/strong>: If MariaDB listens only on a UNIX socket but your JDBC URL assumes TCP (<code>host:port<\/code>), the connection will fail until you add the socket parameter.<\/li>\n\n\n\n<li><strong>Insufficient privileges<\/strong>: The user can connect but lacks privileges on the <code>keycloak<\/code> schema; some setups will surface slightly different errors after initial connection.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Step 1: Navigate to the Configuration File<\/h2>\n\n\n\n<p>When you download and extract Keycloak (for example, version <strong>26.3.4<\/strong>), you\u2019ll find a folder structure like this:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>keycloak-26.3.4\/\n   \u251c\u2500\u2500 bin\/\n   \u251c\u2500\u2500 conf\/\n   \u251c\u2500\u2500 lib\/\n   \u2514\u2500\u2500 ...\n<\/code><\/pre>\n\n\n\n<p>Inside the <strong>conf<\/strong> folder, you\u2019ll find a file named <strong><code>keycloak.conf<\/code><\/strong>.<\/p>\n\n\n\n<p>This file is where Keycloak reads its database configuration details.<\/p>\n\n\n\n<p>The path looks like this:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>\\keycloak-26.3.4\\conf\\keycloak.conf\n<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Step 2: Open and Edit <code>keycloak.conf<\/code><\/h2>\n\n\n\n<p>Open the <code>keycloak.conf<\/code> file in your preferred text editor (Notepad, VS Code, or any IDE).<\/p>\n\n\n\n<p>Here, you can specify database details if you\u2019re connecting to an external database (like PostgreSQL or MySQL). But if you\u2019re just starting out and want Keycloak to <strong>automatically create its database<\/strong>, you don\u2019t need to make changes. Keycloak will use the default configuration and set it up for you.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Step 3: Run the Start Command<\/h2>\n\n\n\n<p>Now, it\u2019s time to launch Keycloak.<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li>Open <strong>Command Prompt (CMD)<\/strong>.<\/li>\n\n\n\n<li>Navigate to the <strong>bin<\/strong> folder inside your Keycloak directory:<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>cd keycloak-26.3.4\\bin\n<\/code><\/pre>\n\n\n\n<p>Run the following command:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>.\/kc.sh start-dev\n<\/code><\/pre>\n\n\n\n<p>This tells Keycloak to start in <strong>development mode<\/strong>. In this mode, Keycloak automatically sets up the necessary database tables for you.<\/p>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n\n<h2 class=\"wp-block-heading\"> Step 4: Database Creation Happens Automatically<\/h2>\n\n\n\n<p>When you run the <code>.\/kc.sh start-dev<\/code> command:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Keycloak connects to the default database (by default, it uses an embedded H2 database).<\/li>\n\n\n\n<li>It <strong>automatically creates all required tables<\/strong> needed for users, roles, clients, sessions, and tokens.<\/li>\n\n\n\n<li>You don\u2019t have to manually create the schema or run SQL scripts.<\/li>\n<\/ul>\n\n\n\n<p>This makes it perfect for testing, learning, or experimenting with Keycloak.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>In plain terms: Keycloak is trying to connect to a MariaDB\/MySQL database named keycloak, but that database doesn\u2019t exist on the host\/port you\u2019ve configured\u2014or the name is&#8230; <\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2833],"tags":[2819,2822,2776,2830,2820,2829,2826,2825,2824,2816,2831,2828,2818,2817,2821,2832,2827,2823,2815],"class_list":["post-3276","post","type-post","status-publish","format-standard","hentry","category-keycloak","tag-jdbc-connection-error","tag-kc-sh-configuration","tag-keycloak","tag-keycloak-database-configuration","tag-keycloak-database-setup","tag-keycloak-database-user-setup","tag-keycloak-db-url","tag-keycloak-docker","tag-keycloak-environment-variables","tag-keycloak-error-1049","tag-keycloak-installation-guide","tag-keycloak-jdbc-url","tag-keycloak-mariadb","tag-keycloak-mysql","tag-keycloak-quarkus","tag-keycloak-sql-error","tag-keycloak-troubleshooting","tag-mariadb-keycloak-integration","tag-unknown-database-keycloak"],"_links":{"self":[{"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/posts\/3276","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/comments?post=3276"}],"version-history":[{"count":1,"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/posts\/3276\/revisions"}],"predecessor-version":[{"id":3277,"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/posts\/3276\/revisions\/3277"}],"wp:attachment":[{"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/media?parent=3276"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/categories?post=3276"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopssupport.in\/blog\/wp-json\/wp\/v2\/tags?post=3276"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}