{"record":{"id":"db883af6bb00e722","repo":"apache/hadoop","slug":"no-keyprovider-has-been-defined","errorCode":null,"errorMessage":"No KeyProvider has been defined","messagePattern":"No KeyProvider has been defined","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"hadoop-common-project/hadoop-kms/src/main/java/org/apache/hadoop/crypto/key/kms/server/KMSWebApp.java","lineNumber":129,"sourceCode":"      reencryptEEKCallsMeter = metricRegistry.register(REENCRYPT_EEK_METER,\n          new Meter());\n      reencryptEEKBatchCallsMeter = metricRegistry.register(\n          REENCRYPT_EEK_BATCH_METER, new Meter());\n      adminCallsMeter = metricRegistry.register(ADMIN_CALLS_METER, new Meter());\n      keyCallsMeter = metricRegistry.register(KEY_CALLS_METER, new Meter());\n      invalidCallsMeter = metricRegistry.register(INVALID_CALLS_METER,\n          new Meter());\n      unauthorizedCallsMeter = metricRegistry.register(UNAUTHORIZED_CALLS_METER,\n          new Meter());\n      unauthenticatedCallsMeter = metricRegistry.register(\n          UNAUTHENTICATED_CALLS_METER, new Meter());\n\n      kmsAudit = new KMSAudit(kmsConf);\n\n      // initializing the KeyProvider\n      String providerString = kmsConf.get(KMSConfiguration.KEY_PROVIDER_URI);\n      if (providerString == null) {\n        throw new IllegalStateException(\"No KeyProvider has been defined\");\n      }\n      KeyProvider keyProvider =\n          KeyProviderFactory.get(new URI(providerString), kmsConf);\n      Preconditions.checkNotNull(keyProvider, String.format(\"No\" +\n              \" KeyProvider has been initialized, please\" +\n              \" check whether %s '%s' is configured correctly in\" +\n              \" kms-site.xml.\", KMSConfiguration.KEY_PROVIDER_URI,\n          providerString));\n      if (kmsConf.getBoolean(KMSConfiguration.KEY_CACHE_ENABLE,\n          KMSConfiguration.KEY_CACHE_ENABLE_DEFAULT)) {\n        long keyTimeOutMillis =\n            kmsConf.getLong(KMSConfiguration.KEY_CACHE_TIMEOUT_KEY,\n                KMSConfiguration.KEY_CACHE_TIMEOUT_DEFAULT);\n        long currKeyTimeOutMillis =\n            kmsConf.getLong(KMSConfiguration.CURR_KEY_CACHE_TIMEOUT_KEY,\n                KMSConfiguration.CURR_KEY_CACHE_TIMEOUT_DEFAULT);\n        keyProvider = new CachingKeyProvider(keyProvider, keyTimeOutMillis,\n            currKeyTimeOutMillis);","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-kms/src/main/java/org/apache/hadoop/crypto/key/kms/server/KMSWebApp.java#L111-L147","documentation":"During KMS webapp initialization (KMSWebApp servlet-context listener), KMS reads hadoop.kms.key.provider.uri (KMSConfiguration.KEY_PROVIDER_URI) from kms-site.xml. If the property is absent it throws IllegalStateException 'No KeyProvider has been defined' and the webapp fails to deploy: the KMS has no backing keystore (KeyProvider) to read/write keys and refuses to start. A distinct follow-on check (Preconditions.checkNotNull) covers the case where the URI is set but no factory can handle its scheme.","triggerScenarios":"Fresh KMS install where kms-site.xml lacks hadoop.kms.key.provider.uri; config file not being loaded because kms.config.dir points at an empty directory; the property name misspelled. Typical valid value: kms://file@/path/keystore or kms://https@host:port/kms (a KMS backed by another KMS).","commonSituations":"New deployments forgetting the keystore URI;分层 deployments where the local KMS should delegate to a remote KMS; config-dir mistakes after moving from /etc/hadoop-kms/conf to a custom path; test setups that copy kms-default.xml only.","solutions":["Add hadoop.kms.key.provider.uri to kms-site.xml, e.g. kms://file@/var/lib/hadoop-kms/keystore (file-backed) or kms://https@kms-host:9600/kms (chained)","Make sure kms.config.dir actually contains the edited kms-site.xml so it is loaded","If the URI is set but you still see the follow-on Preconditions error, check the URI scheme matches a registered KeyProviderFactory (file, kms, jceks, javakeystore)"],"exampleFix":"<!-- kms-site.xml -->\n<property>\n  <name>hadoop.kms.key.provider.uri</name>\n  <value>kms://file@/var/lib/hadoop-kms/keystore</value>\n</property>","handlingStrategy":"validation","validationCode":"Configuration conf = KMSConfiguration.getConfiguration(false, \"kms-site.xml\");\nif (conf.get(KMSConfiguration.KEY_PROVIDER_URI) == null)\n  throw new IllegalStateException(\"kms-site.xml must define hadoop.kms.key.provider.uri\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Include hadoop.kms.key.provider.uri in templated kms-site.xml from day one","Use a config check in deployment pipelines that greps for the key","For chained KMS use the kms:// scheme URI; for file-backed use kms://file@/path"],"tags":["hadoop-kms","configuration","startup-failure","key-provider","missing-config"],"backgroundTag":"missing-required-config-key","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}