Surface project import error in UI

Problem to solve

When GitLab projects are imported into GitLab (via the project importer), the import worker will give up as soon as it hits an error. Currently, the import process will stop and redirect the user to the project page with no warning or error messages.

Intended users

Product Manager, Development Team Lead, Software Developer

Further details

Users often write into Support with questions on why a project imported but is missing various items.

Example resulting issues (with some Support tickets linked in comments):

• https://gitlab.com/gitlab-org/gitlab-ce/issues/62250
• https://gitlab.com/gitlab-org/gitlab-ce/issues/65880
• https://gitlab.com/gitlab-org/gitlab-ce/issues/61934
• https://gitlab.com/gitlab-org/gitlab-ce/issues/66127

Proposal

Surface the error message that is present in json.message log entry. The error may not always make sense to the user, but they can see if it's consistent, file an issue/ticket with the error message, and understand that the import did not succeed.

Feel free to edit the wording to match the style of our other error messages. Perhaps something like:

(JSON message, which already includes error wording). Resulting project is a partial import.

For example:

RuntimeError: Error importing repository into project/path - Failed to set releases: Validation failed: Name can't be blank. Resulting project is a partial import.

Alternatively, use the Project.import_state.last_error

What does success look like, and how can we measure that?

Users at least understand that an error occurred while importing, so the result is a partial import.

Links / references

added DEPRECATED_project import Manage [DEPRECATED] customer devopsmanage internal customer movingtogitlab typefeature + 1 deleted label

changed title from Surface project import error in some way in UI to Surface project import error in UI

changed the description

added to epic &645

added gitlab.com label

added GitLab.com Priority label

removed from epic &645

mentioned in issue #31986 (closed)

mentioned in issue #32498 (closed)

mentioned in issue #32974 (closed)

mentioned in issue #33500 (closed)

mentioned in issue #33958 (closed)

mentioned in issue #34465 (closed)

mentioned in issue #35029 (closed)

mentioned in issue #35482 (closed)

mentioned in issue #35976 (closed)

mentioned in issue #36567 (closed)

mentioned in issue #37182 (closed)

mentioned in issue #37860 (closed)

mentioned in issue #39002 (closed)

mentioned in issue #103403 (closed)

mentioned in issue #121480 (closed)

mentioned in issue #193027 (closed)

mentioned in issue #195099 (closed)

mentioned in issue #196463 (closed)

mentioned in issue #197797 (closed)

mentioned in issue #198979 (closed)

mentioned in issue #201628 (closed)

mentioned in issue #204651 (closed)

mentioned in issue #206814 (closed)

mentioned in issue #207751 (closed)

changed milestone to %Backlog

removed Manage [DEPRECATED] label

marked this issue as related to #195311

mentioned in issue #195311

added [deprecated] Accepting merge requests label

marked this issue as related to #208417 (closed)

mentioned in merge request !25619 (merged)

mentioned in issue #208417 (closed)

Ultimate customer affected by this: https://gitlab.zendesk.com/agent/tickets/157092 (internal link)

It's taken us quite a bit of time to narrow this down and showing something in the UI would have been helpful rather than just giving them a partial project.

added Category:Importers label

added to epic &2959

added UX frontend labels

@amandakhughes This is an issue that should be addressed with the larger Import UX redesign. However, it may also be an opportunity for a small iteration. What would the UX here look like? Do we have a pattern that we could just follow (banner, box, modal, inline message...)?

cc @mikelong

@jhyson What's the status of the backend here? Does it already provide the error info?

@hdelalic I believe we'd use the warning alert component, however, I'm not 100% certain. I'd need to do a bit of investigating unless @tauriedavis would be able to provide guidance. 🙏

@amandakhughes This sounds like it would use our error alert, since the action is failing.

Thanks @tauriedavis ! I appreciate your input.

@hdelalic Let's use the error alert I've created a figma file with options - with and without a title.

1. Is there any action a user can take? Retry?
2. Will the user understand what steps to take to correct the error?
3. Will the user understand the JSON message?

Perhaps @mjang1 could help out with copy. 😄

Is there any action a user can take? Retry?

I was just thinking about this in light of our discussion today about "generic error messages" and wanting them to be actionable.

My suggestion is to ask the user to delete the current project and retry.

Will the user understand what steps to take to correct the error? Will the user understand the JSON message?

I think this greatly depends on the technical level of the user, but much like any other error message, hopefully the user will search for an existing issue to see how it was previously resolved.

We could potentially improve the error messaging in the future, but my suggestion in using the JSON message was a MVC because it's already there. Better an error message that means little but the user can look up, than something generic that is meaningless.

If anyone has better ideas though, please feel free to change the original proposal 🙂

Thanks for the additional input @cynthia !

I like the idea of adding a way for the user to fix the error, in this case it's to remove the project and retry the import.

• Does the user expect to be directed to the Projects page once an import has failed? • What information can we provide the user to help fix the error? • How long with the error message be? Worst-case scenario?

I put together a Figma file with options on how to improve the user experience. Let me know what you think!

Sorry for the delay, I'm just starting to catch up, post 13.0.

When I see the error messages, I see "name can't be blank" in the error message. I try again, but look for all the entries in the UI, to see what was blank.

I'd hope for something more specific, such as "Project slug can't be blank."

Thanks @amandakhughes I like option 2 and made a couple of comments on the Figma. As per my comment on Figma, the only thing I would change is that instead of a "Cancel", maybe have something like "Keep it" to dismiss the banner and let the user use the partial project "as is"

Does the user expect to be directed to the Projects page once an import has failed?

As per my comment on the Figma, currently and what I'd expect is for the user to be redirected to the Project overview page of the newly created project, but with the error messaging

What information can we provide the user to help fix the error?

I'm not sure that there is anything. I'd expect someone to search our issue tracker (or the internet) to see if there is a known bug, and that's true of all error messages?

How long will the error message be? Worst-case scenario?

They can be somewhat long if it includes a path. The longest I've seen would be similar to #214356 (which is a project export issue, but import errors are similar):

Errno::ENOENT: No such file or directory @ rb_sysopen - /var/opt/gitlab/gitlab-rails/shared/external-diffs/merge_request_diffs/mr-54395058/diff-83204365

@amandakhughes hey, sorry for taking so long getting back on this! One thing to note is that both group and project import will suffer from the same/very similar issues here, so it would be ideal if we addressed both at the same time :)

The designs look cool -- I'm really in favour of making the errors less generic so that users are able to debug the failures themselves 🎉

I have a couple of technical notes:

1. I think we currently "soft delete" projects, so I'm not sure if we could redirect the user to perform the import again with the same namespace as the failed import will hang around for a while.
2. There can be more than one error during an import (ie a particular user fails to map, and one issue is invalid). Some of these errors will still count as a "successful" import, whereas others (like invalid file format) are a hard failure.
3. Currently we log most of these errors to the exceptions_json.log file as well as creating an ImportFailure record, so I think we should be able to display each of these errors in the UI. The current behaviour only displays the last error in the UI. Which looks like this in the case of a hard failure:

I think we currently "soft delete" projects, so I'm not sure if we could redirect the user to perform the import again with the same namespace as the failed import will hang around for a while.

Thanks for bringing this up! At the moment, this is only the case for Premium/Silver+ customers, so for those customers we may need #191367 (closed) ; unless the team wants to "bypass" the waiting period for this specific issue

assigned to @amandakhughes

@mjang1 I left a couple of comments for you in the figma file. Let me know what you think of the copy.

@cynthia I believe I've made all of the corrections. Will you check and let me know how everything looks?

Thanks!!

@amandakhughes thanks for "showing" me how comments work in Figma. Comments added. I believe in the mantra "Make every word earn its place."

@mjang1 Ha, Figma is supposed to be user-friendly! How long did it take to figure out how to use the comment feature? 😆

I've added some more comments for you.

@amandakhughes thanks! This looks like a great MVC with a huge UX improvement

Thanks @amandakhughes! I had to refer to the email link to realize -- Oh 10, 11, and 12 are comments with questions 😆 .

I think all is good, thanks for discussing.

Great! We should be all good then. The final design can be found in the figma file.

@mjang1 Thanks for all of your help with the copy. And, for learning how to comment within Figma 😆

@cynthia Thank you so much for your quick responses and suggestions!

Let me know if anyone needs anything else.

I had one last thought but totally optional in possibly simplifying the message by removing the line that is repeated in the button.

Small thing though and shouldn't be a blocker

@cynthia That's a great catch. I agree it's not necessary for the message to be repeated. I've removed it from the error message. 👍

unassigned @amandakhughes

mentioned in merge request !29271 (merged)

mentioned in issue #215441 (closed)

marked this issue as related to #223785 (closed)

added sectiondev label

@hdelalic would it be possible to get this scheduled? I see that a few months ago a bunch of UX work was done. We're continuing to get tickets that are sometimes difficult to solve because the error message isn't surfaced and the user never sees it.

Latest example: https://gitlab.zendesk.com/agent/tickets/182586

~"group::import" is still unable to prioritize this. Our bandwidth is still very small and we are working on issues with higher priorities. :(

added Support Priority label

This is not a project import error, but related to group import error. Looking at the logs, the imported showed a warning Validation failed: Require two factor authentication is forbidden by a top-level group, but it's now shown in the UI.

Related ticket: https://gitlab.zendesk.com/agent/tickets/192993 (internal)

I think it's also better to surface these type of errors in the UI.

changed the description

added Importer:Project Export/Import label

added groupimport and integrate label and removed 1 deleted label

added Support Efficiency label

@nmalcolm discovered https://gitlab.com/gitlab-org/security/gitlab/-/merge_requests/3399#note_1486201498 that we redirect failed imports to the new_project_import_path, which displays the Import by Repository URL import form, regardless of whether that was the type of import or not (or even, if that type of import is enabled as an import source on the instance). This is currently a confusing experience.

The solution would be the same as this issue, to redirect failed imports to a dedicated page that surfaces the project import error in the UI.