fix(route53): improve fromHostedZoneId error message (#20755)

fixes #8406 

----

### All Submissions:

* [ ] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk/aws-route53/lib/hosted-zone.ts

@@ -61,7 +61,8 @@ export class HostedZone extends Resource implements IHostedZone {
   /**
    * Import a Route 53 hosted zone defined either outside the CDK, or in a different CDK stack
    *
-   * Use when hosted zone ID is known. Hosted zone name becomes unavailable through this query.
+   * Use when hosted zone ID is known. If a HostedZone is imported with this method the zoneName cannot be referenced.
+   * If the zoneName is needed then the HostedZone should be imported with `fromHostedZoneAttributes()` or `fromLookup()`
    *
    * @param scope the parent Construct for this Construct
    * @param id  the logical name of this Construct
@@ -71,7 +72,7 @@ export class HostedZone extends Resource implements IHostedZone {
     class Import extends Resource implements IHostedZone {
       public readonly hostedZoneId = hostedZoneId;
       public get zoneName(): string {
-        throw new Error('HostedZone.fromHostedZoneId doesn\'t support "zoneName"');
+        throw new Error('Cannot reference `zoneName` when using `HostedZone.fromHostedZoneId()`. A construct consuming this hosted zone may be trying to reference its `zoneName`. If this is the case, use `fromHostedZoneAttributes()` or `fromLookup()` instead.');
       }
       public get hostedZoneArn(): string {
         return makeHostedZoneArn(this, this.hostedZoneId);
@@ -222,14 +223,17 @@ export class PublicHostedZone extends HostedZone implements IPublicHostedZone {
   /**
    * Import a Route 53 public hosted zone defined either outside the CDK, or in a different CDK stack
    *
+   * Use when hosted zone ID is known. If a PublicHostedZone is imported with this method the zoneName cannot be referenced.
+   * If the zoneName is needed then the PublicHostedZone should be imported with `fromPublicHostedZoneAttributes()`.
+   *
    * @param scope the parent Construct for this Construct
    * @param id the logical name of this Construct
    * @param publicHostedZoneId the ID of the public hosted zone to import
    */
   public static fromPublicHostedZoneId(scope: Construct, id: string, publicHostedZoneId: string): IPublicHostedZone {
     class Import extends Resource implements IPublicHostedZone {
       public readonly hostedZoneId = publicHostedZoneId;
-      public get zoneName(): string { throw new Error('cannot retrieve "zoneName" from an an imported hosted zone'); }
+      public get zoneName(): string { throw new Error('Cannot reference `zoneName` when using `PublicHostedZone.fromPublicHostedZoneId()`. A construct consuming this hosted zone may be trying to reference its `zoneName`. If this is the case, use `fromPublicHostedZoneAttributes()` instead'); }
       public get hostedZoneArn(): string {
         return makeHostedZoneArn(this, this.hostedZoneId);
       }
@@ -368,14 +372,17 @@ export class PrivateHostedZone extends HostedZone implements IPrivateHostedZone
   /**
    * Import a Route 53 private hosted zone defined either outside the CDK, or in a different CDK stack
    *
+   * Use when hosted zone ID is known. If a HostedZone is imported with this method the zoneName cannot be referenced.
+   * If the zoneName is needed then you cannot import a PrivateHostedZone.
+   *
    * @param scope the parent Construct for this Construct
    * @param id the logical name of this Construct
    * @param privateHostedZoneId the ID of the private hosted zone to import
    */
   public static fromPrivateHostedZoneId(scope: Construct, id: string, privateHostedZoneId: string): IPrivateHostedZone {
     class Import extends Resource implements IPrivateHostedZone {
       public readonly hostedZoneId = privateHostedZoneId;
-      public get zoneName(): string { throw new Error('cannot retrieve "zoneName" from an an imported hosted zone'); }
+      public get zoneName(): string { throw new Error('Cannot reference `zoneName` when using `PrivateHostedZone.fromPrivateHostedZoneId()`. A construct consuming this hosted zone may be trying to reference its `zoneName`'); }
       public get hostedZoneArn(): string {
         return makeHostedZoneArn(this, this.hostedZoneId);
       }

packages/@aws-cdk/aws-route53/test/hosted-zone.test.ts

@@ -161,4 +161,19 @@ describe('hosted zone', () => {
       });
     }).toThrow(/crossAccountZoneDelegationRoleName property is not supported without crossAccountZoneDelegationPrincipal/);
   });
+
+  test('fromHostedZoneId throws error when zoneName is referenced', () => {
+    // GIVEN
+    const stack = new cdk.Stack(undefined, 'TestStack', {
+      env: { account: '123456789012', region: 'us-east-1' },
+    });
+
+    // WHEN
+    const hz = HostedZone.fromHostedZoneId(stack, 'HostedZone', 'abcdefgh');
+
+    // THEN
+    expect(() => {
+      hz.zoneName;
+    }).toThrow('Cannot reference `zoneName` when using `HostedZone.fromHostedZoneId()`. A construct consuming this hosted zone may be trying to reference its `zoneName`. If this is the case, use `fromHostedZoneAttributes()` or `fromLookup()` instead.');
+  });
 });