Process

The migration of an existing DNS Console zone into the Hetzner Console must be triggered manually, no zones are migrated automatically. The migration is a one-way process, it cannot be undone! You can start the migration from either the DNS Console or the DNS API.

There is no downtime of DNS resolution during migration. The migration does not modify a zone, all settings will remain unchanged. However, it may be necessary to modify a zone before migration to comply with the new requirements.

Please note that Hetzner DNS comes with a new API, integrated in the Cloud API. Hetzner offers multiple official integrations, such as hcloud CLI, hcloud-go, hcloud-python, Terraform, Ansible, external-dns and cert-manager.

The DNS API can no longer be used for a zone after migration.

Requirements

• Correct authoritative name servers

  Your zone must contain the correct authoritative name servers in its apex (@) NS records.

  These may be any of the following sets:

  Set 1	Set 2	Set 3
  hydrogen.ns.hetzner.com. oxygen.ns.hetzner.com. helium.ns.hetzner.de.	ns1.first-ns.de. robotns2.second-ns.de. robotns3.second-ns.com.	ns1.your-server.de. ns.second-ns.com. ns3.second-ns.de.

  The "Name server" tab in the DNS Console lists the correct name server set for your zone.

  Your zone must not mix name servers of different sets. There is no benefit of doing so, the migration will not be possible in that case. All three name servers assigned to your zone must be present as NS records, it is not enough to list one or two name servers.

  The zone may contain additional, external (non-Hetzner) name servers if you're running a multi-provider DNS configuration.

• Identical TTLs for records with same name and type

  All records with the same type and name must also share the same TTL. For example, a common error is that TXT or MX records are configured with different TTLs:

  ; Name	TTL		Type	Value
  
  ; Incorrect:
  @	3600	IN	MX	10 mx1.example.com.
  @	7200	IN	MX	20 mx2.example.com. ; Must be 3600 as well.
  
  ; Correct:
  @	3600	IN	MX	10 mx1.example.com.
  @	3600	IN	MX	20 mx2.example.com.

Migration via DNS Console

Make sure your zone fulfills the requirements.

1. Navigate to your zone in the DNS Console.
2. Open the Settings tab.
3. Click Migrate to Hetzner Console, which opens a dialog.
4. Enter the zone name into the input field to confirm the migration.
5. Click Migrate zone.
6. After successful migration, click Go to Hetzner Console.

In the Hetzner Console, you'll see a project called DNS Migrated. The DNS tab will show your zone. If desired, you can transfer the zone to a different project.

In case of validation issues, please refer to Common migration errors and how to fix them. For problems not listed there, please contact our support.

Migration via DNS API

If you do not have an API token yet, generate one on your DNS Console account page.

Make sure your zone fulfills the requirements.

1. Navigate to your zone in the DNS Console.
2. Copy your zone's ID from the browser URL. For example, if the URL is https://dns.hetzner.com/zone/DDDF8sdogJGmb4cSRA4hqU, your zone ID is DDDF8sdogJGmb4cSRA4hqU.
3. Send an HTTP request to the DNS API, for example using curl:

   curl -X POST 'https://dns.hetzner.com/api/v1/migration/<zone ID>' \ # Fill in your ID, e.g. DDDF8sdogJGmb4cSRA4hqU
     -H 'Auth-API-Token: <API token>' \                                # Fill in your API token
     -d '{"no_dry_run": true}'

   A successful migration returns an HTTP code 200 and an empty response body ({}). Complete documentation of the migration endpoint is available in the DNS API docs.

In the Hetzner Console, you'll see a project called DNS Migrated. The DNS tab will show your zone. If desired, you can transfer the zone to a different project.

In case of validation issues, please refer to Common migration errors and how to fix them. For problems not listed there, please contact our support.

Common migration errors and how to fix them

Zone has missing or invalid nameserver sets

API response body:

{
  "error": {
    "message": "Zone has missing or invalid nameserver sets",
    "code": 400,
  },
}

This validation error occurs if your zone does not contain the correct NS records, as described in Requirements: Correct authoritative name servers. A common mistake is that a zone is either missing an assigned name server, or that name servers from different sets are mixed.

For example, this zone is missing the third assigned name server robotns3.second-ns.com.:

To fix this, add the missing name server NS record.

In another example, this zone is mixing different name servers sets, and contains NS records for name servers not assigned to it:

To fix this, remove all NS records containing name servers not assigned to the zone.

Invalid delegation of parent zone

API response body:

{
  "error": {
    "message": "Invalid delegation of parent zone",
    "code": 400,
  },
}

This validation error occurs if your domain is not correctly configured to use Hetzner's name servers. Check the domain settings at your registrar (where you bought the domain), and make sure the name servers are set to exactly the same values as the Hetzner name servers assigned to your zone (see Requirements: Correct authoritative name servers).

For example, if the name servers assigned to your zone are hydrogen.ns.hetzner.com., oxygen.ns.hetzner.com. & helium.ns.hetzner.de., these must be listed as name servers in your domain registrars settings. Do not include any other Hetzner name servers. After fixing this, it can take a few minutes to hours before your changes are propagated across the DNS. Please try the migration again afterwards.

Your domain may delegate to additional, external (non-Hetzner) name servers if you're running a multi-provider DNS configuration. This will not prevent a migration.

Zone is incorrectly delegated (lame delegation)

API response body:

{
  "error": {
    "message": "Zone is incorrectly delegated (lame delegation)",
    "code": 400,
  },
}

The domain is delegated to name servers that don't know about the zone, or answer with an error. The zone is therefore not used, it can be safely deleted from the DNS Console.

If you just registered the domain and want to migrate your zone to the Hetzner Console, please either wait a few hours, or delete the zone from the DNS Console and create the zone in the Hetzner Console directly.

Domain is not registered

API response body:

{
  "error": {
    "message": "Domain is not registered",
    "code": 400,
  },
}

The domain is not registered at any registrar, and is therefore not used. It can be safely deleted from the DNS Console.

If you just registered the domain and want to migrate your zone to the Hetzner Console, please either wait a few hours, or delete the zone from the DNS Console and create the zone in the Hetzner Console directly.

TXT records must be fully escaped with double quotes

API response body:

{
  "error": {
    "message": "Request invalid",
    "code": 400,
      "migration_errors": {
      "zonefile.records[0].value": [
        "TXT records must be fully escaped with double quotes",
      ],
    },
  },
}

All TXT record values must be enclosed in double quotes. If your TXT record consists of multiple strings, make sure each of them is fully enclosed:

If necessary, double quotes itself can be escaped using a slash: " \"escaped quotes\" ".

Differing record TTLs

API response body:

{
  "error": {
    "message": "Request invalid",
    "code": 400,
    "migration_errors": {
      "zonefile.ttl": [
        "(@, MX) has differing record TTLs",
      ],
    },
  },
}

Records with the same name and type must also share the same TTL, as described in Requirements: Identical TTLs for records with same name and type. For example, these two MX records do not share the same TTL:

To fix this, make sure the TTL of all records with the same name and type share the same TTL.

TTL must be at least 60s

API response body:

{
  "error": {
    "message": "Request invalid",
    "code": 400,
    "migration_errors": {
      "zonefile.ttl": [
        "must be at least 60s",
      ],
    },
  },
}

All record TTLs must be set to at least 60 seconds. For example, the TTL of the following A record is too small:

To fix this, make sure all records in your zone have a TTL of at least 60, especially not 0.

Duplicate value

API response body:

{
  "error": {
    "message": "Request invalid",
    "code": 400,
    "migration_errors": {
      "zonefile.records[0].value": [
        "duplicate value '"example"'",
      ],
    },
  },
}

Make sure that your zone does not contain records with the same name, type, and value. A common error is that there are duplicate TXT records with exactly the same value. You can safely delete one of the records in this case.

Record name has uppercase letters

API response body:

{
  "error": {
    "message": "Request invalid",
    "code": 400,
    "migration_errors": {
      "zonefile.records[0].name": [
        "has uppercase characters",
      ],
    },
  },
}

This validation error occurs whenever any record name contains uppercase letters. For example, this A record was created with the name WWW, which is not valid.

To fix this, convert all names to lowercase letters only.

Zone limit exceeded

API response body:

{
  "error": {
    "message": "Zone limit exceeded",
    "code": 400,
  },
}

Your Hetzner Console already contains the maximum allowed zones (default 25). Please contact our support to increase the limit.

Records per zone limit exceeded

API response body:

{
  "error": {
    "message": "Records per zone limit exceeded",
    "code": 400,
  },
}

Your zone has too many records and exceeds the Hetzner Console limit (default 500). Please contact our support to increase the limit.

Project limit reached

API response body:

{
  "error": {
    "message": "Project limit reached",
    "code": 400,
  },
}

Your account has reached its project limit, the DNS Migrated project cannot be created. Please contact our support to increase the limit.