How to catch the detailed error message when the download fails

[coder-dongjiayi]

How to catch the detailed error message when the download fails

[781flyingdutchman]

Also a good idea. Perhaps the description is the body if it's not empty, and the reasonphrase if it is? Body is not always available (eg a malformed URL never gets to a body). What do you think?

[781flyingdutchman]

Good idea! Let me look into that.

[781flyingdutchman]

The error message is logged. It is not available programmatically.

[coder-dongjiayi]

I need the error message for improve product experience when the download fails。Whether it is possible to programmatically catch this error message。

[781flyingdutchman]

I see. It's not at the moment but let me think a bit about this. You would need access to an Error or Exception object that triggered the failure, right? A string representation of the error probably isn't enough?

[coder-dongjiayi]

yes, Error or Exception is ok!

[781flyingdutchman]

Hi @coder-dongjiayi I've added functionality to capture the error programmatically and was wondering if you can help me test it and comment. You can access this version on a different branch, so change your pubspec.yaml as follows:

background_downloader:
    git:
      url: https://github.com/781flyingdutchman/background_downloader.git
      ref: error

You need to register a different statuscallback with the signature void Function(Task task, TaskStatus status, TaskError? taskError) by calling FileDownloader().registerCallbacks(taskStatusCallbackWithError: your_callback). You will then get status updates that, if status is TaskStatus.failed, includes a TaskError object. That object has three properties:

1. an ErrorType (httpresponse, fileSystem, url, connection, resume, general) to capture the general nature of the error
2. an optional httpResponseCode (or 0 or -1 if not available)
3. a description as a String

For example, if you get a 403 error, the TaskType will be TaskType.httpResponse, httpResponseCode = 403 and description is "Forbidden".

My hope is that the categorization makes it easier to process the error programmatically, but be aware that it is not possible to have consistent error messages between platforms. As an example, the description for the 403 error is "Forbidden" on Android and "forbidden" (note the lowercase) on iOS. Testing for different errors therefore remains challenging, but I hope this helps with the use case you have in mind.

Could you please test this in various ways and let me know your feedback?

Thanks!

[coder-dongjiayi]

hi, @781flyingdutchman
I just saw that I've integrated this branch into our app. I will be feedback to you with our test results。

[cal-g]

Hi @781flyingdutchman, Thanks for the package.
Would it be possible to also save these errors in the database as part of the TaskRecord model ?

[781flyingdutchman]

Ok, added in the latest 'error' branch - please pull and test!
Also, I just upgraded to Flutter 3.7.12 (from 3.7.10) and Dart 2.19.6 (from a slightly earlier version of Dart) and suddenly my file comparison test fails on Android. Could I ask you to run the Integration tests (in the Example folder) on an Android emulator or device and let me know if the test named 'enqueue and test file equality' passes or fails? Thanks!

[cal-g]

Hi @781flyingdutchman , thanks for the changes.
I tested on iOS and Android and is good.
Also ran the integration tests for the error branch in the Example folder on an Android emulator (I do not have a real Android device to test on) and all the tests including 'enqueue and test file equality' passed. I ran the test on an Android 13.0 arm64 emulator while on Flutter 3.7.12 (Dart 2.19.6).

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.7.12, on macOS 13.0 22A380 darwin-arm64, locale en-US)
[✓] Android toolchain - develop for Android devices (Android SDK version 33.0.2)
[✓] Xcode - develop for iOS and macOS (Xcode 14.3)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2022.2)
[✓] VS Code (version 1.77.3)
[✓] Connected device (4 available)
[✓] HTTP Host Availability

• No issues found!

[lyio]

Is the same information available when I use a listener instead of the callback?

[781flyingdutchman]

@cal-g thanks! And does the change meet your (and @coder-dongjiayi) needs?
@lyio good catch! Added an error property to the TaskStatusUpdate that is sent to the listener at every status change. Note the value is nullable and will always be null if the status is not TaskStatus.failed, but should not be null if it is.
Updated on the error branch.

[lyio]

@781flyingdutchman that was fast, thank you for that addition. Is there a particular reason the TaskError is not extending Error?

[781flyingdutchman]

Also a good question. Let me think a bit about this - a few quick thoughts:

1. It's not really a Dart error (it is not thrown anywhere) so not entirely convinced it adds anything. What do you see as the value of it extending Error or Exception?
2. I realize that according to Dart convention these should be called Exceptions, not Errors (they are not programmer issues), so if we extend it should be Exception, and if we don't I think I need to change the name to Task exception and error to exception

Let me know what you think!

[cal-g]

@781flyingdutchman I was testing the sample app which has a url https://avmaps-dot-bbflightserver-hrd.appspot.com/public/get_current_app_data which fails with a 403 (Forbidden) and the response is Not authorized when checking on chrome devtools or Postman.

The field values of the TaskError models are:
type = ErrorType.httpResponse
httpResponseCode = 403
description = Forbidden/forbidden

Is it possible to set the description value to Not authorized instead i.e body of the error response ? because the meaning of the codes are standard.

[cal-g]

I see, that works fine too.

[coder-dongjiayi]

Hi @781flyingdutchman
On the iOS platform, when a timeout occurs, the error message is not callbacked to Flutter. I noticed that the timeoutIntervalForResource parameter is set to 4 * 60 * 60.0, which is too long. Can this parameter be set on the Flutter side?
Xcode conlose log print Task <7666D994-305E-4A0F-80BE-B468EA06DDD4>.<1> finished with error [-1001] Error Domain=NSURLErrorDomain Code=-1001 "The request timed out." UserInfo={NSURLSessionDownloadTaskResumeData={length = 5120, bytes = 0x62706c69 73743030 d4010203 04050607 ... 00000000 00001358 }, _NSURLErrorFailingURLSessionTaskErrorKey=BackgroundDownloadTask <7666D994-305E-4A0F-80BE-B468EA06DDD4>.<1>, _kCFStreamErrorCodeKey=-2103, _NSURLErrorRelatedURLSessionTaskErrorKey=( "BackgroundDownloadTask <7666D994-305E-4A0F-80BE-B468EA06DDD4>.<1>", "LocalDownloadTask <7666D994-305E-4A0F-80BE-B468EA06DDD4>.<1>" ), NSLocalizedDescription=The request timed out., _kCFStreamErrorDomainKey=4, NSErrorFailingURLStringKey=https://1xxxxxxx2304/f0.mp4, NSErrorFailingURLKey=https://xxxxxxx/f0.mp4}
the err message was not caught。

[781flyingdutchman]

@cal-g I changed the approach as suggested to one with a base class TaskException and then subclasses for the types of exception (e.g. TaskHttpException). I also provide the server content/body as the description for TaskHttpExceptions only. Implemented so far only on Android and Desktop on the branch error2. Will implement in iOS later and merge into error but if you want it to test it now for Android, you can. Quite a big change so you'll have to change some of your code.

[781flyingdutchman]

@coder-dongjiayi this issue and the discussion here is not yet published, so can you confirm you are using the error branch and not the regular package?
The timeoutIntervalForResource paramter is not the typical HTTP request timeout. Instead it is the total time a Task stays alive, and a Task may have to wait for WiFi it is reasonable to set this value high (in fact, the default value is even higher). Therefore there is no compelling reason to be able to set this iOS-only parameter on the Flutter side

[coder-dongjiayi]

@781flyingdutchman I'm sure it's in the error branch。Let's assume the following scenario
I am downloading a 10M file, but the file server may be far away from the user. For example, the file server is in China, but the user may be in England. Users are waiting for the file download is complete, if timeoutIntervalForResource is very large, the user may have been waiting for the download page. At this time, we may set the timeout time to 60 seconds. After 60 seconds, if the file server does not respond, it indicates that the request time out is requested. We need to inform the user that the network is abnormal and need to re-download. I think timeoutIntervalForResource this parameter should be exposed to developers, by a business to determine how much the value should be

[781flyingdutchman]

@coder-dongjiayi can you start a new issue for the resource timeout (and perhaps copy your comments from here) so we can keep this issue about capturing error messages generally?

[781flyingdutchman]

Implemented in V6.0.0:
If a task fails, the TaskStatusUpdate will contain a TaskException that provides information about the type of exception (e.g. a TaskFileSystemException indicates an issue with storing or retrieving the file) and contains a description and (for TaskHttpException only) the httpResponseCode. If tasks are tracked, the The following TaskException subtypes may occur:

• TaskException (general exception)
• TaskFileSystemException (issue retrieving or storing the file)
• TaskUrlException (issue with the url)
• TaskConnectionException (issue with the connection to the server)
• TaskResumeException (issue with pausing or resuming a task)
• TaskHttpException (issue with the HTTP connection, e.g. we received an error response from the server, captured in httpResponseCode)