abpframework/abp · error · CliUsageException

DeepL auth key is missing!

Error message

DeepL auth key is missing!

What it means

Thrown by TranslateCommand.ExecuteAsync when --online is set but --deepl-auth-key is not provided. DeepL API requires an authentication key for programmatic translation access. Note: there is a code bug on line 55 where GetOrNull(Options.DeepLAuthKey.Short, Options.DeepLAuthKey.Short) passes the same key twice instead of Short and Long, but since DeepLAuthKey only defines Short = 'deepl-auth-key' (no Long constant), it still works correctly by accident.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/TranslateCommand.cs:58

        {
            var inputFile = Path.Combine(currentDirectory, commandLineArgs.Options.GetOrNull(Options.File.Short, Options.File.Long) ?? "abp-translation.json");
            await ApplyAbpTranslateInfoAsync(currentDirectory, inputFile);
            return;
        }

        var targetCulture = commandLineArgs.Options.GetOrNull(Options.Culture.Short, Options.Culture.Long);
        if (targetCulture == null)
        {
            throw new CliUsageException("Target culture is missing!" + Environment.NewLine + Environment.NewLine + GetUsageInfo());
        }

        // Translate online
        if (commandLineArgs.Options.ContainsKey(Options.Online.Long))
        {
            var authKey = commandLineArgs.Options.GetOrNull(Options.DeepLAuthKey.Short, Options.DeepLAuthKey.Short);
            if (authKey == null)
            {
                throw new CliUsageException("DeepL auth key is missing!" + Environment.NewLine + Environment.NewLine + GetUsageInfo());
            }
            await TranslateAbpTranslateInfoAsync(currentDirectory, targetCulture, referenceCulture, allValues, authKey);
            return;
        }

        // Generate abp-translation.json file
        var outputFile = Path.Combine(currentDirectory, commandLineArgs.Options.GetOrNull(Options.Output.Short, Options.Output.Long) ?? "abp-translation.json");
        await GenerateAbpTranslateInfoAsync(currentDirectory, targetCulture, referenceCulture, allValues, outputFile);
    }

    private Task GenerateAbpTranslateInfoAsync(string currentDirectory, string targetCulture, string referenceCulture, bool allValues, string outputFile)
    {
        Logger.LogInformation("Abp translate...");
        Logger.LogInformation("Target culture: " + targetCulture);
        Logger.LogInformation("Reference culture: " + referenceCulture);
        Logger.LogInformation("Output file: " + outputFile);
        if (allValues)
        {

View on GitHub (pinned to 7ed43b1931)

Solutions

  1. Sign up for a DeepL API account at deepl.com/pro (free tier available)
  2. Add --deepl-auth-key <your-deepl-api-key> to the command
  3. If you don't want online translation, remove --online to generate the translation file locally for manual translation
  4. Store the key in an environment variable to avoid pasting it each time

Example fix

// before
abp translate -c zh-Hans --online

// after
abp translate -c zh-Hans --online --deepl-auth-key YOUR_DEEPL_KEY
Defensive patterns

Strategy: validation

Validate before calling

// Validate DeepL auth key when using --online
var isOnline = commandLineArgs.Options.ContainsKey("online");
var hasAuthKey = commandLineArgs.Options.ContainsKey("deepl-auth-key");

if (isOnline && !hasAuthKey)
{
    Console.Error.WriteLine("Error: --deepl-auth-key is required when using --online.");
    return;
}

Try / catch

try
{
    await translateCommand.ExecuteAsync(commandLineArgs);
}
catch (CliUsageException ex) when (ex.Message.Contains("DeepL auth key is missing"))
{
    Console.Error.WriteLine("Missing --deepl-auth-key. Get a free key at deepl.com/pro");
}

Prevention

When it happens

Trigger: Running 'abp translate --culture <c> --online' without the --deepl-auth-key flag. For example: 'abp translate -c zh-Hans --online' without the key.

Common situations: Developer doesn't have a DeepL API account, forgets to include the key, or doesn't realize --online requires it. DeepL offers a free tier with 500,000 characters/month.

Related errors

AI-assisted analysis of abpframework/abp@7ed43b1931 (2026-08-13). Data as JSON: /api/errors/a1251566a33ce118. Report an issue: GitHub.