cefsharp/CefSharp · error · ArgumentNullException

frame

Error message

frame

What it means

Thrown by DownloadUrlAsync when the frame argument is null. The method needs a valid frame to create the GET request on the CEF UI thread, so it guards up front with ArgumentNullException. This is distinct from the IsValid check that follows — null means the caller never obtained or passed a frame reference at all.

Source

Thrown at CefSharp.Core/WebBrowserExtensionsEx.cs:108

                    .Build();

                var urlRequest = frame.CreateUrlRequest(request, urlRequestClient);
            });
        }

        /// <summary>
        /// Downloads the specified <paramref name="url"/> as a <see cref="T:byte[]"/>.
        /// Makes a GET Request.
        /// </summary>
        /// <param name="frame">valid frame</param>
        /// <param name="url">url to download</param>
        /// <param name="urlRequestFlags">control caching policy</param>
        /// <returns>A task that can be awaited to get the <see cref="T:byte[]"/> representing the Url</returns>
        public static Task<byte[]> DownloadUrlAsync(this IFrame frame, string url, UrlRequestFlags urlRequestFlags = UrlRequestFlags.None)
        {
            if (frame == null)
            {
                throw new ArgumentNullException(nameof(frame));
            }

            if (!frame.IsValid)
            {
                throw new Exception("Frame is invalid, unable to continue.");
            }

            var taskCompletionSource = new TaskCompletionSource<byte[]>(TaskCreationOptions.RunContinuationsAsynchronously);

            //Can be created on any valid CEF Thread, here we'll use the CEF UI Thread
            Cef.UIThreadTaskFactory.StartNew(delegate
            {
                var request = frame.CreateRequest(false);

                request.Method = "GET";
                request.Url = url;
                request.Flags = urlRequestFlags;

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Ensure the browser is initialized (await browserInitialized task / WaitForInitializationAsync) before accessing MainFrame.
2. Guard for null before calling: if (frame != null) await frame.DownloadUrlAsync(url);
3. Use WebBrowserExtensions.ThrowExceptionIfFrameNull for consistent validation in your own code.

Example fix

// before
var bytes = await frame.DownloadUrlAsync(url);

// after
await browser.WaitForInitializationAsync(); // or check IsBrowserInitialized
var frame = browser.GetMainFrame();
var bytes = await frame.DownloadUrlAsync(url);

await browser.WaitForInitializationAsync();
var frame = browser.GetMainFrame();
if (frame == null) return Array.Empty<byte>();
var data = await frame.DownloadUrlAsync(url);

public static bool IsFramePresent(IFrame f) => f != null;

try { return await frame.DownloadUrlAsync(url); }
catch (ArgumentNullException ex) when (ex.ParamName == "frame") { /* browser not ready */ }

When it happens

Trigger: Calling frame.DownloadUrlAsync(url) where frame is null — e.g. browser.MainFrame accessed before browser initialization completed, or a variable that was never assigned.

Common situations: Calling MainFrame on a ChromiumWebBrowser whose IsBrowserInitialized is still false. Disposing the browser and then awaiting a pending async operation that captured the now-null frame reference.

Related errors

• An IFrame instance is required.
• IBrowser
• otherRequestContext
• requestContextHandler
• settings

AI-assisted analysis of cefsharp/CefSharp@16bc6e0711 (2026-08-13). Data as JSON: /api/errors/439d54fed825997d. Report an issue: GitHub.