What causes "ERROR: Remote server returns '{response.StatusCode}'" in abpframework/abp?

Re-authenticate with 'abp login ' to refresh the access token, then retry.

abpframework/abp · error · Exception

ERROR: Remote server returns '{response.StatusCode}'

Error message

ERROR: Remote server returns '{response.StatusCode}'

What it means

Thrown by AuthService.CheckMultipleOrganizationsAsync when the HTTP GET to the abp.io license endpoint returns a non-success status code. The CLI contacts account.abp.io to determine whether a username belongs to more than one organization; any 4xx/5xx is surfaced as a generic remote error wrapping the status code.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Auth/AuthService.cs:141

            {
                await LogoutAsync(accessToken);
            }

            File.Delete(CliPaths.Lic);
        }
    }

    public async Task<bool> CheckMultipleOrganizationsAsync(string username)
    {
        var url = $"{CliUrls.AccountAbpIo}api/license/check-multiple-organizations?username={username}";

        var client = CliHttpClientFactory.CreateClient();

        using (var response = await client.GetHttpResponseMessageWithRetryAsync(url, CancellationTokenProvider.Token, Logger))
        {
            if (!response.IsSuccessStatusCode)
            {
                throw new Exception($"ERROR: Remote server returns '{response.StatusCode}'");
            }

            await RemoteServiceExceptionHandler.EnsureSuccessfulHttpResponseAsync(response);

            var responseContent = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<bool>(responseContent);
        }
    }

    private async Task LogoutAsync(string accessToken)
    {
        try
        {
            var client = CliHttpClientFactory.CreateClient();
            var content = new StringContent(
                JsonSerializer.Serialize(new { token = accessToken }),
                Encoding.UTF8, "application/json"
            );

View on GitHub (pinned to 7ed43b1931)

Solutions

Re-authenticate with 'abp login <username>' to refresh the access token, then retry.
Check network connectivity and proxy settings; ensure account.abp.io is reachable (the CLI uses a retry policy, so transient failures are already retried).
If the server is down (5xx/429), wait and retry later.
For CI environments, run login in a prior step and persist the token, or skip license-dependent commands.

Example fix

# before: token expired, command fails
abp suite install
# after: re-login then retry
abp login your@username.com
abp suite install

Defensive patterns

Strategy: retry

Validate before calling

// Pre-check connectivity and a valid token before calling the license endpoint.
if (string.IsNullOrWhiteSpace(await authService.GetAccessTokenAsync()))
{
    throw new InvalidOperationException("Not logged in. Run 'abp login' first.");
}
if (!await networkProbe.CanReachAsync(new Uri(CliUrls.AccountAbpIo)))
{
    throw new InvalidOperationException("account.abp.io is not reachable; check network/proxy.");
}

Type guard

public static bool IsTransientFailure(HttpStatusCode code) =>
    (int)code is >= 500 and (int)HttpStatusCode.ServiceUnavailable or 429;

Try / catch

try
{
    var multiple = await authService.CheckMultipleOrganizationsAsync(username);
}
catch (Exception ex) when (ex.Message.Contains("Remote server returns", StringComparison.Ordinal))
{
    logger.LogError(ex, "License check failed; re-login or retry later.");
    // Re-authenticate or surface to the user; do not silently swallow.
    throw;
}

Prevention

Run 'abp login' before license-dependent commands and keep the token current.
Ensure network/proxy allows account.abp.io in CI.
Surface status codes clearly to users instead of hiding the generic exception.
Cache license-check results to reduce calls to the remote endpoint.

When it happens

Trigger: client.GetHttpResponseMessageWithRetryAsync(url) returns a response where IsSuccessStatusCode is false. Causes include 401/403 (auth/expired token), 404 (unknown user), 5xx (server outage), or network-level failures that still produce a status code after retries.

Common situations: Expired or missing ABP CLI login token; the account.abp.io service is temporarily down; rate limiting (429); corporate proxy returning an error page/status; the username does not map to a licensed account; offline/network-restricted CI environment.

Related errors

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