ICP custom domains: registration stuck with null canister_id

On 2026-10-26 a developer reported that a custom domain registration on ICP's HTTP gateway service was stuck. For hours, the status API returned "registration_status":"registering" with "canister_id":null for icpcoins.eu, and it cleared on its own by the morning of 2026-10-27. If you point a domain at a canister, validate your DNS records and ownership file before you send the registration request, because the docs give no way to cancel a registration once it has started.

What happened

The report is in a forum thread opened on 2022-10-06. In that thread a boundary node team researcher, rbirkner, wrote on 2022-10-07 that custom domains would use "a CNAME in your DNS entry" plus a canister mapping, with TLS terminated at the boundary nodes. The feature has shipped since then. A redesigned REST API under /custom-domains/v1/{domain} was announced on the forum in November 2025.

On 2026-10-26 user Henn91 posted the status response for his domain:

{"status":"success","message":"Registration status of the domain","data":{"domain":"icpcoins.eu","canister_id":null,"registration_status":"registering"}}

The facts from the thread, in order:

1. 2026-10-26, first post: the status stays registering. He asks if there is a timeout or if DFINITY has to cancel the registration by hand, and says he cannot stop or delete it. He suggests an automatic delete after 30 minutes.
2. 2026-10-26, about two hours later: "Now 3 or 4 hours passed, still stuck". He concludes that there is no expiry timer. He also says Caffeine users had domains stuck "for days" and thinks it may be the same bug. That link is his guess.
3. 2026-10-27, 06:39: "Its working now". He asks for a fix so the service no longer returns success when canister_id is null, and says removing and re-adding a domain is slow.

DFINITY had not replied in the thread by that last post. No root cause has been published.

One detail matters if you read this response. In the official docs, a status query that works returns "status": "success" with the message "Registration status of the domain". So the top-level success means the status query worked. It does not mean the domain is registered. The useful signal is the pair inside data: canister_id is null while the status is registering. In the docs, both the validate response and the accepted registration response include the canister ID, so a null value means the service has no canister mapped to the domain.

Who is affected and why it matters

This affects anyone who serves a canister frontend on their own domain through the HTTP gateways, including apps built with Caffeine. The docs list four states: registering, registered, expired and failed. The docs say registration "takes a few minutes". They do not say how long registering can last or what happens when it stalls.

The docs also leave no clean way out. A POST while another task is running can return conflict ("another registration task is in progress. Retry after a few minutes"). The documented removal steps start with deleting your _canister-id TXT record and _acme-challenge CNAME, then calling DELETE. If a registration stalls, you can poll, retry later or ask on the forum. As the reporter found, you cannot stop it yourself through the documented API.

The Internet Identity cost is real. II derives user principals from the origin. If users sign in at <canister-id>.icp.net today and you move them to a custom domain, they get new principals unless you set up alternative origins ("Use one derivation origin" in the docs).

What to do now

These commands come from the current ICP custom domains guide, which uses the icp.net host. Replace CUSTOM_DOMAIN with your domain.

Before registering:

1. Add the three DNS records:

2. Serve /.well-known/ic-domains from the canister, with one domain per line. On the legacy asset canister, add { "match": ".well-known", "ignore": false } to .ic-assets.json5.
3. Confirm the TXT record and the file from the outside:

dig TXT _canister-id.CUSTOM_DOMAIN
curl -sL https://<canister-id>.icp.net/.well-known/ic-domains

You need exactly one _canister-id TXT record. If you use Cloudflare for DNS, turn off Universal SSL and set the records to "DNS only".

4. Validate, and do not continue until the response shows your canister ID and "validation_status": "valid":

curl -sL -X GET "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN/validate" | jq

Register and watch:

# Register
curl -sL -X POST "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq

# Poll status: registering -> registered
curl -sL -X GET "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq

The POST response should repeat your canister ID. If a status response shows canister_id: null, check the TXT record again with dig. The docs give no timeout, so if the record stays null and registering, post the domain and the full status response on the forum.

To change or remove a mapping later:

• To point the domain at another canister, change the _canister-id TXT record, then send curl -sL -X PATCH "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq.
• To remove the domain, delete the TXT and _acme-challenge records, then send curl -sL -X DELETE "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq. After that, a status GET should return 404.

On the frontend, set the agent host when the app runs on a custom domain. Otherwise the agent sends API calls to the page origin, and those calls fail:

import { HttpAgent } from "@icp-sdk/core/agent";
const isProduction = process.env.NODE_ENV === "production";
const host = isProduction ? "https://icp-api.io" : undefined;
const agent = await HttpAgent.create({ host });

Caveats

This is one user's report. The thread does not say what caused the stall or whether anything was changed on the service side. The reporter thinks the earlier Caffeine domain delays were the same bug, but that has not been confirmed. Once registered appears, the docs say to allow 5 to 10 more minutes for the change to reach all HTTP gateways.