abpframework/abp · error · CliUsageException

You can only create a new preview solution with preview CLI

Error message

You can only create a new preview solution with preview CLI version. Update your ABP CLI to the preview version.

What it means

Thrown by ProjectCreationCommandBase when the --preview flag is set but the installed ABP CLI version is not a prerelease/build. Under #if !DEBUG, the code fetches the current CLI version and checks cliVersion.IsPrerelease; if false, the user is told to update to a preview CLI. This prevents creating preview solutions with a stable CLI, which could generate incompatible template output.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/ProjectCreationCommandBase.cs:97

    {
        var version = commandLineArgs.Options.GetOrNull(Options.Version.Short, Options.Version.Long);

        if (version != null)
        {
            Logger.LogInformation($"Version: {version}");
        }

        var preview = commandLineArgs.Options.ContainsKey(Options.Preview.Long);
        if (preview)
        {
            Logger.LogInformation("Preview: yes");

#if !DEBUG
            var cliVersion = await CliVersionService.GetCurrentCliVersionAsync();

            if (!cliVersion.IsPrerelease)
            {
                throw new CliUsageException(
                    "You can only create a new preview solution with preview CLI version." +
                    " Update your ABP CLI to the preview version.");
            }
#endif
        }

        var pwa = commandLineArgs.Options.ContainsKey(Options.ProgressiveWebApp.Short);
        if (pwa)
        {
            Logger.LogInformation("Progressive Web App: yes");
        }

        var databaseProvider = GetDatabaseProvider(commandLineArgs);
        if (databaseProvider != DatabaseProvider.NotSpecified)
        {
            Logger.LogInformation($"Database provider: {databaseProvider}");
        }

View on GitHub (pinned to 7ed43b1931)

Solutions

1. Update to the preview CLI: `dotnet tool update --global Volo.Abp.Studio.Cli --prerelease` (or the relevant preview package source)
2. Remove the --preview flag if you want to use the stable CLI: `abp new MyProject`
3. Verify the installed CLI version with `abp --version` and confirm it shows a prerelease suffix (e.g., -rc, -preview)

Example fix

// before
abp new MyProject --preview
// (running stable CLI)

// after
dotnet tool update --global Volo.Abp.Studio.Cli --prerelease
abp new MyProject --preview

// Check CLI version before allowing preview solution creation
var cliVersion = await cliVersionService.GetCurrentCliVersionAsync();
var wantsPreview = commandLineArgs.Options.ContainsKey(Options.Preview.Long);
if (wantsPreview && !cliVersion.IsPrerelease)
{
    Console.Error.WriteLine("Error: Preview solutions require a preview CLI. Update with --prerelease.");
    return;
}

try
{
    await projectCreationCommand.ExecuteAsync(commandLineArgs);
}
catch (CliUsageException ex) when (ex.Message.Contains("preview solution with preview CLI"))
{
    logger.LogError("Update CLI to preview: dotnet tool update -g Volo.Abp.Studio.Cli --prerelease");
}

When it happens

Trigger: Running `abp new MyProject --preview` with a stable (non-preview) CLI build installed. CliVersionService.GetCurrentCliVersionAsync() returns a version whose IsPrerelease is false. In DEBUG builds this check is skipped.

Common situations: Developer installs the standard ABP CLI package but tries to scaffold a preview template. Version mismatch between the CLI and the template engine's preview expectations. Common when switching between stable and preview ABP versions.

Related errors

• Project name is missing!
• This command should be run inside a folder that contains a m
• The option you provided for Database Provider is invalid!
• The option you provided for Database Management System is in
• The option you provided for Mobile App is invalid!

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