Providers
Troubleshooting access
Fix DNS API authentication, permission, IP allow-list, and endpoint errors. Read saved failures, restore deleted credentials, and gather useful diagnostics.
6 min read
On this page
Provider API errors in DNSMigrator fall into five adapter categories: authentication, permission, API restriction, IP allow-list, and network. Fix the provider-side cause first, then use Check access on the saved connection to replace Access failed with a fresh result.
How to fix provider API errors#
When you select Connect, DNSMigrator stores the validated, encrypted credential and immediately calls the provider’s access check. A failed check does not discard the connection. Its row shows Access failed and the safe message returned by the adapter.
Read the complete row message
Open Connections and find the failed provider. The text beside Access failed often names the rejected field, missing permission, disabled API or allow-list requirement.
Open the matching provider guide
Go to Supported providers, choose the provider and compare the credential fields and preview/apply permissions with the values in its official console.
Fix access at the provider
Activate or replace the token, add the required scope, enable API access, or update the source-IP allow-list. DNSMigrator cannot alter the provider credential’s scope.
Run the check again
Return to Connections and select Check access. A successful response changes the row to Active and records the reported Read or Read + write scope.
Error categories#
Adapters normalize access checks to the following codes. The UI currently shows the message rather than the code, so use the wording and HTTP status as clues.
| Code | Typical cause | What to check |
|---|---|---|
auth | The token, key pair, password, signature, TSIG key or temporary session is invalid, inactive or expired | Paste a newly issued value, preserve the full JSON or key formatting, check account/tenant identifiers, and confirm the credential is active |
forbidden | Authentication succeeded but the identity cannot list zones, read records, change records or access the selected account | Add the exact read or write permissions in the provider guide; confirm resource, project, subscription, account and zone scope |
api-restricted | The provider account has API access disabled or restricted by a provider setting or account policy | Enable API access in the provider console, complete any provider-required account setting, then issue a compatible credential |
ip-not-allowed | The provider rejected DNSMigrator’s source address, or DNSMigrator’s endpoint guard blocked the supplied endpoint | Add the displayed egress address to the provider allow-list; for self-hosted endpoints, use a public, permitted address and port |
network | DNS, TLS, routing or connectivity failed before a usable provider response arrived | Check hostname resolution, public reachability, certificate validity, firewall rules and provider status, then retry |
The shared HTTP client maps HTTP 401 to auth and 403 to forbidden. Individual adapters refine provider-specific responses; for example, a 403 can become api-restricted when the provider explicitly says its DNS API is unavailable. Timeouts are reported through the access-check network category. The shared HTTP client retries HTTP 429 responses, and retries server errors for idempotent requests, before returning the final message.
Authentication failures#
Create a replacement credential rather than repeatedly editing an unknown value. Secret fields are trimmed by the connect form, while JSON credentials must parse as the whole document. If the form says That isn't valid JSON. Paste the whole file., copy the complete service-account file rather than one property from it.
Common checks include:
- the credential belongs to the account, tenant, project or subscription entered in the other fields;
- a token is active and has not passed its provider-side expiration;
- paired values, such as an API key and secret, came from the same credential;
- a TSIG name, algorithm and secret match the authoritative server; and
- two-factor settings are compatible with the provider’s API flow.
DNSMigrator stores no edited replacement into an existing connection. If the saved secret itself is wrong, select Remove, confirm Remove and delete credentials, then create a new connection with the corrected value.
Permission failures#
A read check and an apply need different capabilities. A connection can be Active with Read and still be unsuitable as a destination. Compare the provider page’s preview and apply permissions before running a migration.
For Cloudflare, scope the token to the intended zones and grant the record permission required for the action. For Route 53, reopen the generated CloudFormation setup with Include write access (needed to apply to Route 53) if the role was created read-only. DNSMigrator’s generated read policy and optional write policy are separate.
Also check resource placement. A valid cloud identity may be unable to see a zone because the form names the wrong project, resource group, subscription, compartment or server ID. If no zones appear in a migration picker, run Check access, then verify those provider-specific fields.
API and IP restrictions#
Some providers require API access to be enabled before any key works. Follow the generated provider guide’s official link; DNSMigrator does not bypass account-level API eligibility or activation rules.
Providers with source-IP controls must see DNSMigrator’s static egress address. The Namecheap guide uses the Allow-list address shown in the dialog. If Namecheap displays Not available on this server yet., that DNSMigrator deployment has no configured static egress IP and cannot create the connection.
For other allow-listed providers, use the egress address shown by their setup guide. Do not allow-list your laptop’s address: access checks and jobs run from the DNSMigrator server.
Self-hosted endpoint failures#
Self-hosted APIs have an additional outbound request guard. It rejects local or reserved hostnames, every DNS answer must be public, and the connection is pinned to the validated address for the request. The hosted form accepts only https:// API URLs. Standard permitted API ports are 443, 8443, 8080, 8081, 3000, 10443 and 33073; the AXFR/RFC 2136 connection uses TCP port 53.
| Message pattern | Cause | Fix |
|---|---|---|
| “local or reserved hostname” | The name is localhost or ends in a reserved local suffix | Publish a dedicated public DNS name |
| “private or reserved address” | A literal or any DNS answer is private, loopback, link-local, CGNAT, documentation, multicast or otherwise reserved | Use a public endpoint; split-horizon DNS and private tunnels are not accepted |
| “Port … is not allowed” | The URL or DNS server uses a port outside the guard’s allow-list | Move the service behind HTTPS on a permitted port, or use TCP 53 for a DNS transfer/update connection |
| “did not respond in time” | The firewall, route or service did not complete the request | Allow the server’s egress address and confirm the service listens publicly |
| TLS or generic network error | The certificate chain or hostname is invalid, or the connection was reset | Install a publicly trusted certificate for the exact hostname and test the public endpoint |
See Self-hosted providers for the complete reachability model and PowerDNS for a concrete HTTPS API example.
Deleted credentials#
A row marked Credentials deleted has no encrypted secret left. Check access is intentionally unavailable. Create a new connection and select it in future work; migration history remains attached to the old row.
The default purge deadline moves forward after any credential use, including an access check. Read Credential security before relying on the displayed deletion time.
What to include when asking for help#
Send the provider name, connection status, exact redacted message, whether you expected read or write access, and the time of the failed check. Include the connection label, not the credential. Never send API tokens, passwords, private keys, TSIG secrets, webhook signing secrets or full service-account JSON.
The Activity log can confirm that a connection check and credential load were recorded, but its By label does not reliably distinguish user and worker rows. Provider errors are redacted where the adapter knows the submitted secret, and unexpected exceptions are replaced with a generic message.