abpframework/abp · error · CliUsageException

Use command: abp new Acme.BookStore -v version

Error message

Use command: abp new Acme.BookStore -v version

What it means

Thrown by `AbpIoSourceCodeStore.GetAsync` when no version was specified by the user AND the remote service returned no latest version (i.e. `GetLatestSourceCodeVersionAsync` returned null, typically because the remote is unreachable). The CLI first lists locally cached templates as a hint, then throws a `CliUsageException` instructing the user to pass an explicit version.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/ProjectBuilding/AbpIoSourceCodeStore.cs:88

        var userSpecifiedVersion = version != null;
        var latestVersion = version ?? await GetLatestSourceCodeVersionAsync(name, type, null, includePreReleases);
        if (version == null)
        {
            if (latestVersion == null)
            {
                Logger.LogWarning("The remote service is currently unavailable, please specify the version.");
                Logger.LogWarning(string.Empty);
                Logger.LogWarning("Find the following template in your cache directory: ");
                Logger.LogWarning("\tTemplate Name\tVersion");

                var templateList = GetLocalTemplates();
                foreach (var cacheFile in templateList)
                {
                    Logger.LogWarning($"\t{cacheFile.TemplateName}\t\t{cacheFile.Version}");
                }

                Logger.LogWarning(string.Empty);
                throw new CliUsageException("Use command: abp new Acme.BookStore -v version");
            }

            version = latestVersion;
        }

        if (type == SourceCodeTypes.Template)
        {
            var currentCliVersion = await CliVersionService.GetCurrentCliVersionAsync();
            var templateVersion = SemanticVersion.Parse(version);

            var outputWarning = false;
            if (!trustUserVersion)
            {
                if (currentCliVersion.Major != templateVersion.Major || currentCliVersion.Minor != templateVersion.Minor)
                {
                    // major and minor version are different
                    outputWarning = true;
                }

View on GitHub (pinned to 7ed43b1931)

Solutions

  1. Re-run with an explicit version from the cached list printed just above the error: `abp new Acme.BookStore -v <version>`.
  2. Restore connectivity to `www.abp.io` / `account.abp.io` and retry without `-v`.
  3. Configure the CLI proxy if behind a corporate firewall (`abp config` / `appsettings.json`).

Example fix

# before
abp new Acme.BookStore
# after (offline / remote unavailable)
abp new Acme.BookStore -v 8.3.0
Defensive patterns

Strategy: fallback

Validate before calling

// Pass an explicit version so the CLI never depends on the remote latest lookup.
string version = await ResolveVersionFromCacheOrConfigAsync()
    ?? throw new InvalidOperationException("Cannot determine version offline; pass -v explicitly.");
await cli.RunAsync(new[] { "new", projectName, "-v", version });

Try / catch

try { await cli.RunAsync(new[] { "new", projectName }); }
catch (CliUsageException ex) when (ex.Message.Contains("abp new Acme.BookStore -v"))
{
    // parse the cached template versions from logs and retry with -v
}

Prevention

When it happens

Trigger: Running `abp new <ProjectName>` without `-v` while the abp.io version API is unavailable (offline, blocked, or erroring), so the CLI cannot determine the latest template version.

Common situations: No/intermittent internet connection; behind a corporate proxy that blocks `www.abp.io`; abp.io outage; running `abp new` in an air-gapped environment.

Related errors

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