apache/hadoop · error · SASTokenProviderException

Unable to load user-bound SAS token provider class: {e}

Error message

Unable to load user-bound SAS token provider class: {e}

What it means

Catch-all inside getUserBoundSASTokenProvider: any exception other than SASTokenProviderException thrown while resolving, instantiating, or initializing the user-bound SAS token provider is rethrown as SASTokenProviderException with 'Unable to load user-bound SAS token provider class: ' plus the cause. The original failure (ClassNotFoundException, IllegalAccessException/InstantiationException, or an error inside the provider's initialize(rawConfig, accountName)) is chained.

Source

Thrown at hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/AbfsConfiguration.java:1704

        throw new SASTokenProviderException(String.format(
            "\"%s\" must be set for user-bound SAS auth type.",
            FS_AZURE_SAS_TOKEN_PROVIDER_TYPE));
      }

        SASTokenProvider sasTokenProvider = ReflectionUtils.newInstance(
            customSasTokenProviderImplementation, rawConfig);
        if (sasTokenProvider == null) {
          throw new SASTokenProviderException(String.format(
              "Failed to initialize %s", customSasTokenProviderImplementation));
        }
        LOG.trace("Initializing {}", customSasTokenProviderImplementation.getName());
        sasTokenProvider.initialize(rawConfig, accountName);
        LOG.trace("{} init complete", customSasTokenProviderImplementation.getName());
        return sasTokenProvider;
    } catch (SASTokenProviderException e) {
      throw e;
    } catch (Exception e) {
      throw new SASTokenProviderException(
          "Unable to load user-bound SAS token provider class: " + e, e);
    }
  }

  /**
   * Returns both the AccessTokenProvider and the SASTokenProvider
   * when auth type is UserboundSASWithOAuth.
   *
   * @return Object[] where:
   *   [0] = AccessTokenProvider
   *   [1] = SASTokenProvider
   * @throws AzureBlobFileSystemException if provider initialization fails
   */
  public Object[] getUserBoundSASBothTokenProviders()
      throws AzureBlobFileSystemException {
    AuthType authType = getEnum(FS_AZURE_ACCOUNT_AUTH_TYPE_PROPERTY_NAME,
        AuthType.SharedKey);
    if (authType != AuthType.UserboundSASWithOAuth) {

View on GitHub (pinned to 2add963021)

Solutions

Inspect e.getCause() — it carries the real error such as ClassNotFoundException or the provider's own exception from initialize().
Fix the class name in fs.azure.sas.token.provider.type and confirm the jar is on both driver and executor classpaths.
Ensure every config key the provider's initialize() needs is present in the job Configuration.
Rebuild the provider against the same Hadoop/hadoop-azure version the cluster runs.

Example fix

// before
<property><name>fs.azure.sas.token.provider.type</name><value>com.example.UserSASProvider</value></property>
<!-- actual class lives at com.example.providers.UserSASProvider -->

// after
<property><name>fs.azure.sas.token.provider.type</name><value>com.example.providers.UserSASProvider</value></property>

Defensive patterns

Strategy: try-catch

Validate before calling

Class<?> cls;
try {
  cls = Class.forName(conf.get("fs.azure.sas.token.provider.type"));
} catch (ClassNotFoundException | NullPointerException e) {
  throw new IOException("SAS token provider class not loadable: " + e, e);
}
if (!SASTokenProvider.class.isAssignableFrom(cls)) {
  throw new IOException("Provider does not implement SASTokenProvider: " + cls);
}

Try / catch

try {
  FileSystem fs = path.getFileSystem(conf);
} catch (SASTokenProviderException e) {
  Throwable cause = e.getCause(); // CNFE, IllegalAccess, or provider initialize() failure
  LOG.error("User-bound SAS provider load failed: {}", cause, e);
  throw e;
}

Prevention

Ship the provider jar to every driver/executor classpath.
Test provider initialize() with the production configuration in CI.
Pin the hadoop-azure version the provider is compiled against.

When it happens

Trigger: fs.azure.sas.token.provider.type contains a typo or names a class missing from the driver/executor classpath (ClassNotFoundException); the provider class lacks an accessible no-arg constructor; or the provider's initialize() throws because its own required config keys are absent.

Common situations: Provider jar not shipped with the job (YARN containers, Spark executors); provider reads account-specific settings that were not propagated; provider compiled against an older hadoop-azure ABI; shaded jars that relocate the class away.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/08d591074d88f6f8. Report an issue: GitHub.