elsa-workflows/elsa-core · error · InvalidOperationException

Elsa Platform artifact exceeds the configured runtime size…

Error message

Elsa Platform artifact exceeds the configured runtime size limit.

What it means

DownloadArtifactAsync streams an artifact from the Elsa Platform runtime to a destination while enforcing a configured maximum size (_options.MaxArtifactBytes). As soon as the cumulative byte count exceeds that limit, the copy loop aborts and this InvalidOperationException is thrown, protecting the host from unbounded downloads exhausting memory or disk.

Solutions

1. Increase MaxArtifactBytes in the platform runtime client options to a value larger than the expected artifact size.
2. Verify the artifact on the server: check it does not accidentally contain large binaries or duplicated payloads that inflate its size.
3. If the artifact is legitimately huge, split it into smaller artifacts or stream it through a mechanism not bounded by this client limit.
4. Add pre-flight size checking (artifact metadata/content-length) so users get a clear error before streaming starts.

Example fix

// before
options.MaxArtifactBytes = 1 * 1024 * 1024; // 1 MB
// after
options.MaxArtifactBytes = 64 * 1024 * 1024; // 64 MB, room for real artifacts

var size = await GetArtifactSizeAsync(artifactId); // e.g. content-length / metadata
if (size > options.MaxArtifactBytes)
    throw new InvalidOperationException($"Artifact is {size} bytes, exceeding limit {options.MaxArtifactBytes}.");

try
{
    await client.DownloadArtifactAsync(artifactId, destination, ct);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("exceeds the configured runtime size limit"))
{
    logger.LogWarning(ex, "Artifact download rejected: size limit exceeded.");
}

When it happens

Trigger: Calling DownloadArtifactAsync for an artifact whose total size is larger than MaxArtifactBytes configured in the platform runtime client options; the exception is raised mid-stream after the first chunk pushes total past the limit.

Common situations: Deploying a large recipe/artifact bundle (large workflow export, big embedded files) while the client was configured with a small or default MaxArtifactBytes; limits tightened for security without updating environments that ship big artifacts.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• A configuration key is required.
• A configured default role no longer exists.
• A workflow definition or artifact-relative path is required.
• Adapter ' ' does not provide a settings migration from…
• Adapter ' ' has an invalid settings migration from version…

AI-assisted analysis of elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/d4de31313124acb7. Report an issue: GitHub.

Appendix: source

Thrown at src/modules/Elsa.Platform.Integration/Services/PlatformRuntimeCommandClient.cs:137

        var relative = path.StartsWith("/api/", StringComparison.OrdinalIgnoreCase)
            ? path
            : $"/api/workspaces/{_options.WorkspaceId:D}{path}";
        return new Uri($"{endpoint.AbsoluteUri.TrimEnd('/')}{relative}");
    }

    private async Task CopyBoundedAsync(Stream source, Stream destination, CancellationToken cancellationToken)
    {
        var buffer = new byte[81920];
        long total = 0;
        while (true)
        {
            var read = await source.ReadAsync(buffer, cancellationToken);
            if (read == 0)
                return;

            total += read;
            if (total > _options.MaxArtifactBytes)
                throw new InvalidOperationException("Elsa Platform artifact exceeds the configured runtime size limit.");

            await destination.WriteAsync(buffer.AsMemory(0, read), cancellationToken);
        }
    }

    private static JsonSerializerOptions CreateJsonOptions()
    {
        var options = new JsonSerializerOptions(JsonSerializerDefaults.Web);
        options.Converters.Add(new JsonStringEnumConverter(allowIntegerValues: false));
        return options;
    }
}

View on GitHub (pinned to fe9217bdfa)