Cysharp/UniTask · error · UnityWebRequestException

unityWebRequest.error

Error message

unityWebRequest.error

What it means

Thrown by UnityWebRequestAsyncOperationAwaiter.GetResult() (line 1018) — the awaiter for `await unityWebRequestAsyncOperation` — when UnityWebRequest.IsError() returns true. IsError() maps to a connection error, protocol error (HTTP 4xx/5xx), or data-processing error (Unity 2020.2+) / isHttpError||isNetworkError (older). The failing request is wrapped in UnityWebRequestException, which exposes .Error, .ResponseCode, .Text (download body), and .ResponseHeaders; its Message is built from unityWebRequest.error plus the body text.

Source

Thrown at src/UniTask/Assets/Plugins/UniTask/Runtime/UnityAsyncExtensions.cs:1018

                if (continuationAction != null)
                {
                    asyncOperation.completed -= continuationAction;
                    continuationAction = null;
                    var result = asyncOperation.webRequest;
                    asyncOperation = null;
                    if (result.IsError())
                    {
                        throw new UnityWebRequestException(result);
                    }
                    return result;
                }
                else
                {
                    var result = asyncOperation.webRequest;
                    asyncOperation = null;
                    if (result.IsError())
                    {
                        throw new UnityWebRequestException(result);
                    }
                    return result;
                }
            }

            public void OnCompleted(Action continuation)
            {
                UnsafeOnCompleted(continuation);
            }

            public void UnsafeOnCompleted(Action continuation)
            {
                Error.ThrowWhenContinuationIsAlreadyRegistered(continuationAction);
                continuationAction = PooledDelegate<AsyncOperation>.Create(continuation);
                asyncOperation.completed += continuationAction;
            }
        }

View on GitHub (pinned to ceac8d6946)

Solutions

1. Wrap the await in try/catch(UnityWebRequestException) and branch on .ResponseCode/.Error.
2. For transient failures (ResponseCode == 0 / connection error), retry with backoff.
3. Pre-validate URL, headers, and auth before sending; refresh tokens on 401 rather than treating it as fatal.
4. Pass a CancellationToken via .WithCancellation() to abort hung requests and handle the resulting cancellation/error.

Example fix

// before
var op = UnityWebRequest.Get(url).SendWebRequest();
var req = await op; // throws UnityWebRequestException on any error

// after
try {
    var op = UnityWebRequest.Get(url).SendWebRequest();
    var req = await op;
    var body = req.downloadHandler.text;
} catch (UnityWebRequestException ex) {
    Debug.LogWarning($"{ex.ResponseCode} {ex.Error}\n{ex.Text}");
}

// Pre-flight input checks (cannot prevent runtime network failures)
if (string.IsNullOrWhiteSpace(url)) throw new ArgumentException("url required", nameof(url));
if (!Uri.TryCreate(url, UriKind.Absolute, out var uri)) throw new ArgumentException("invalid url", nameof(url));

bool IsWebError(Exception ex) => ex is UnityWebRequestException uwe
    && (uwe.ResponseCode == 0
        || (uwe.ResponseCode >= 400 && uwe.ResponseCode < 600));

try {
    var op = UnityWebRequest.Get(url).SendWebRequest();
    var req = await op;
    // use req.downloadHandler.text
} catch (UnityWebRequestException ex) {
    // ex.ResponseCode==0 => connection/abort; 4xx/5xx => protocol error
    if (ex.ResponseCode == 0) await RetryAsync();
    else HandleHttpError(ex);
}

When it happens

Trigger: Awaiting a UnityWebRequestAsyncOperation (or calling .ToUniTask() / .WithCancellation() on it) whose request failed: network unreachable, DNS failure, connection reset, request aborted on cancellation, HTTP 4xx/5xx response, or a download/upload handler data-processing error.

Common situations: Device offline or flaky network; wrong/unreachable URL; expired or missing auth token (401/403); server 5xx or CORS; self-signed/untrusted certificate; the request aborted because a CancellationToken fired (WithCancellation aborts via webRequest.Abort()).

Related errors

• Can not trigger itself in iterating.
• handler
• Delay does not allow minus delayFrameCount. delayFrameCount:
• Delay does not allow minus delayTimeSpan. delayTimeSpan:
• The tasks argument contains no tasks.

AI-assisted analysis of Cysharp/UniTask@ceac8d6946 (2026-08-13). Data as JSON: /api/errors/088df0d2b1b63de4. Report an issue: GitHub.