anomalyco/sst · error · VisibleError

The DNS record "${partial.name}" cannot be created because t

Error message

The DNS record "${partial.name}" cannot be created because the domain name does not match the hosted zone "${zone.name}" (${zoneId}).

What it means

When creating a DNS record, SST resolves the Route53 hosted zone (either explicitly given via `args.zone` or auto-discovered). This VisibleError is thrown in lookupZone when the record's domain name is not a subdomain of the hosted zone's name, meaning the record cannot live in that zone.

Source

Thrown at platform/src/components/aws/dns.ts:186

  }

  function _createRecord(
    namePrefix: string,
    partial: Omit<route53.RecordArgs, "zoneId">,
    opts: ComponentResourceOptions,
  ) {
    return output(partial).apply((partial) => {
      const nameSuffix = logicalName(partial.name);
      const zoneId = lookupZone();
      const dnsRecord = createRecord();
      return dnsRecord;

      function lookupZone() {
        if (args.zone) {
          return output(args.zone).apply(async (zoneId) => {
            const zone = await route53.getZone({ zoneId });
            if (!partial.name.replace(/\.$/, "").endsWith(zone.name)) {
              throw new VisibleError(
                `The DNS record "${partial.name}" cannot be created because the domain name does not match the hosted zone "${zone.name}" (${zoneId}).`,
              );
            }
            return zoneId;
          });
        }

        return new HostedZoneLookup(
          `${namePrefix}${partial.type}ZoneLookup${nameSuffix}`,
          {
            domain: output(partial.name!).apply((name) =>
              name.replace(/\.$/, ""),
            ),
          },
          opts,
        ).zoneId;
      }

View on GitHub (pinned to a0bd20f762)

Solutions

Correct the domain name in the record so it matches (is a subdomain of) the hosted zone name
Verify `args.zone` points to the hosted zone ID for the actual domain — check with `aws route53 list-hosted-zones`
Remove the explicit `zone` argument and let SST auto-discover the zone from the record's domain
If the domain is not in Route53 at all, either register/transfer it to Route53 or use your registrar's DNS instead of SST's Route53 DNS-validated component

Example fix

// before
new sst.aws.DnsRecord("Cname", {
  name: "api.example.com",
  type: "CNAME",
  value: target,
  zone: "Z0123456789OTHER", // zone for other.com
});
// after
new sst.aws.DnsRecord("Cname", {
  name: "api.example.com",
  type: "CNAME",
  value: target,
  zone: "Z0123456789EXAMPLE", // zone for example.com
});

Defensive patterns

Strategy: validation

Validate before calling

import { Route53 } from "aws-sdk"; // or use aws cli output
async function zoneMatches(record: string, zoneId: string) {
  const zone = await new Route53().getZone({ Id: zoneId }).promise();
  return record.replace(/\.$/, "").endsWith(zone.Name!.replace(/\.$/, ""));
}

Type guard

function isSubdomainOf(record: string, zoneName: string): boolean {
  return record.replace(/\.$/, "").endsWith(zoneName.replace(/\.$/, ""));
}

Try / catch

try {
  new sst.aws.DnsRecord("Cname", { name, type: "CNAME", value, zone: zoneId });
} catch (e) {
  if (e instanceof Error && e.message.includes("does not match the hosted zone")) {
    console.error(`Record ${name} does not belong to zone ${zoneId}; fix the domain or the zone id`);
  } else throw e;
}

Prevention

Verify hosted zone IDs with `aws route53 list-hosted-zones` before hardcoding them
Keep record domains and zone ids sourced from the same config constant
Omit `zone` and let SST auto-discover the zone when possible
Ensure the domain's DNS is actually hosted in Route53 before using Route53 DNS components

When it happens

Trigger: `args.zone` is set to a zoneId whose zone name (from `route53.getZone`) does not suffix-match `partial.name` after stripping a trailing dot — e.g. record `api.example.com` in a zone for `other.com`.

Common situations: Passing the wrong hosted zone ID in a custom domain config; a typo in the domain or zone name; the domain registered in Route53 differs from the domain being configured (e.g. www vs apex or a staging domain); DNS records defined in a shared helper that receives mismatched domain/zone values.

Related errors

AI-assisted analysis of anomalyco/sst@a0bd20f762 (2026-08-30). Data as JSON: /api/errors/d453439ed8c963fb. Report an issue: GitHub.