'Field discovery failed for Drupal core version 7' errors if migration source database key is not 'migrate'

Problem/Motivation

In the migrate upgrade using Drush documentation, it shows an example of the database settings for a migration. In this example it uses the settings.php database key migrate. But in my own site, I was using the key drupal7 for my Drupal 7 database.

Everything seemed to work correctly, and indeed most (if not all?) of my content, comments, settings, etc. were migrated after running migrate-upgrade and migrate-import

However, every time I ran migrations, I'd get notices like:

 [notice] Field discovery failed for Drupal core version 7. Did this site have the CCK or Field module installed? Error: No database connection configured for source plugin d7_field_instance
 [notice] Processed 1 item (1 created, 0 updated, 0 failed, 0 ignored) - done with 'upgrade_d7_user'
...
 [notice] Field discovery failed for Drupal core version 7. Did this site have the CCK or Field module installed? Error: No database connection configured for source plugin d7_field_instance
 [notice] Processed 15 items (15 created, 0 updated, 0 failed, 0 ignored) - done with 'upgrade_d7_field_instance'

I was worried this might be pointing at some errors during migration. I spot-checked the migrate_map_* tables and didn't see anything strange going on. I spot-checked some of the migrated data from the Drupal 7 site, and again, nothing seemed wrong there.

In the end, after digging through the FieldDiscovery class, I gave up, but before closing out of the session I did one more Google search in desparation, and found this thread by DelishCreative. In it, she mentioned she was having similar strange behavior with her migrations, until she renamed her source database key to migrate:

So the moral of the story kids: Don't name your migration DB group anything other than "migrate".

So... it seems that having the database key be migrate is not an actual requirement (and hasn't been in the past, when I've done other migrations). It seems like it's a bug that migrations throw these errors when a database is set up with a different key (like drupal7, in my case).

If you must name your database key migrate for everything to work, then maybe that should be made explicit in the migration documentation...

(Fix on my Drupal 8 site was here: https://github.com/geerlingguy/jeffgeerling-com/commit/3f6ad0efa24768453...).

Steps to reproduce

Proposed resolution

Putting this work around here so it is easier to find.
huzooka debugged this problem while working on a Media Migration issue, 3180710#comment-14075072. In #19 huzooka suggests the resetting the migrate.fallback_state_key, after using drush migrate:upgrade,.

drush php:eval \
  "\Drupal::state()->set('source_db_connection', [
    'key' => [db-key-of-source-site],
    'target' => 'default',
  ]);"

drush php:eval \
  "\Drupal::state()->set('migrate.fallback_state_key', 'source_db_connection');"

Suggestions for a proper fix are:

• Update the README in Migrate Upgrade to document the behavior
• Anything else?

Remaining tasks