nopSolutions/nopCommerce · error · NopException

Failed to download certificate

Error message

Failed to download certificate

What it means

Thrown when ServiceClient.DownloadCertificateImage(companyId, certificateId, null, CertificatePreviewType.Pdf) returns null. The Avalara SDK returns null when the certificate image/PDF cannot be retrieved.

Source

Thrown at src/Plugins/Nop.Plugin.Tax.Avalara/Services/AvalaraTaxManager.cs:1710

    /// <summary>
    /// Download a PDF file for the certificate
    /// </summary>
    /// <param name="certificateId">The unique ID number of the certificate</param>
    /// <returns>
    /// A task that represents the asynchronous operation
    /// The task result contains the file details
    /// </returns>
    public async Task<FileResult> DownloadCertificateAsync(int certificateId)
    {
        return (await HandleFunctionAsync(() =>
        {
            if (_avalaraTaxSettings.CompanyId is null)
                throw new NopException("Company not selected");

            var file = ServiceClient
                .DownloadCertificateImage(_avalaraTaxSettings.CompanyId.Value, certificateId, null, CertificatePreviewType.Pdf)
                ?? throw new NopException("Failed to download certificate");

            return Task.FromResult(file);
        })).Result;
    }

    /// <summary>
    /// Get an existing invitation to upload certificates on the external website
    /// </summary>
    /// <param name="customer">Customer</param>
    /// <returns>
    /// A task that represents the asynchronous operation
    /// The task result contains the URL to redirect customer
    /// </returns>
    public async Task<string> GetInvitationAsync(Customer customer)
    {
        return (await HandleFunctionAsync(async () =>
        {
            if (_avalaraTaxSettings.CompanyId is null)

View on GitHub (pinned to 64bdf2ff08)

Solutions

1. Verify the certificateId still exists via ListCertificatesForCustomer before offering the download.
2. Check Avalara permissions for the configured license key (needs certificate read/download scope).
3. Retry after confirming the certificate has a generated preview in the Avalara admin UI.

Example fix

// before
var file = ServiceClient
    .DownloadCertificateImage(_avalaraTaxSettings.CompanyId.Value, certificateId, null, CertificatePreviewType.Pdf)
    ?? throw new NopException("Failed to download certificate");

// after — verify existence and give a clearer error
var file = ServiceClient.DownloadCertificateImage(_avalaraTaxSettings.CompanyId.Value, certificateId, null, CertificatePreviewType.Pdf);
if (file is null)
    throw new NopException($"Certificate {certificateId} not available for download (missing or not yet rendered)");

var exists = (await ServiceClient.ListCertificatesForCustomerAsync(_avalaraTaxSettings.CompanyId.Value, customerId.ToString(), null, null, null, null, null))?.value?.Any(c => c.id == certificateId) ?? false;
if (!exists) return NotFound();

try { return await DownloadCertificateAsync(certificateId); }
catch (NopException ex) when (ex.Message.Contains("Failed to download certificate"))
{ _logger.LogWarning(ex, "Certificate {Id} unavailable", certificateId); return NotFound(); }

When it happens

Trigger: Downloading a certificateId that no longer exists; the certificate has no PDF preview generated yet; insufficient permissions for the license key on that certificate; transient SDK failure.

Common situations: Stale certificateId in a link after the certificate was revoked/deleted in Avalara; CertCapture still processing the uploaded image (no PDF rendered yet); license key lacks download scope.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• Failed to delete customer
• Failed to get customer's certificates
• Failed to get invitation
• No tax category found with the specified id
• No record found

AI-assisted analysis of nopSolutions/nopCommerce@64bdf2ff08 (2026-08-13). Data as JSON: /api/errors/b66957f882248cf1. Report an issue: GitHub.