Power Platform refuses to generate the API endpoint when the environment identifier (and the Dataverse host it builds) contains characters outside the allowed set of letters, digits, and dashes. The ~default suffix is the most common culprit: the default environment's internal name carries a tilde, the connector derives a host name from it, and the tilde fails DNS-safe validation before any URL exists. The fix is to point the connection at an environment whose identifier already passes the rule, or to rename that identifier, not to retry the generation.
What the Validation Error Actually Checks
The message is a host-name validation failure wearing an identifier label. Power Platform composes the Dataverse endpoint from the environment's unique name, so contoso-prod becomes something like contoso-prod.crm.dynamics.com, and that string has to survive the same character rules as any DNS label: letters, digits, and hyphens only.
The ~default value is a legacy internal alias for the tenant's default environment, the one Microsoft creates automatically for every tenant. A tilde cannot appear in a host name under the DNS naming rules published in the IETF's RFC 1123, because only a-z, 0-9, and - are valid label characters there, so the generator rejects it before it ever calls the service.
Two boundaries matter. The check is client-side in most tools, which means it fires instantly and produces no server log entry you can diagnose, and it inspects the identifier you selected rather than the friendly display name shown in the admin center. That gap explains why the environment looks perfectly normal in the list yet still fails.
If your error names a different character, the cause is the same. Spaces, underscores, periods, accented letters, and non-Latin scripts all fail the same validation. The error text simply reports the identifier it received. Read the string, not the label.
Why the Default Environment Reports ~default
Every tenant ships with one default environment, and its internal identifier was never designed for URL construction. Microsoft's environment documentation describes the default environment as the tenant-wide fallback where every licensed user can create resources, and its unique name is fixed rather than editable through the normal admin path.
That fixed alias is what leaks into connectors and CLI output. When a connection or endpoint generator asks Power Platform for the environment's identity, it can receive the internal alias instead of a clean unique name, and ~default is exactly that alias. The tilde is a marker, not a typo.
The practical consequence is that generating an endpoint directly against the default environment is where this error concentrates. You can browse the default environment and build apps inside it, because those operations use IDs rather than host names. Endpoint generation does not, and that is the fork in the road.
Older tenants sometimes display slightly different internal names for their default environment, depending on when the tenant was provisioned. Confirm the actual identifier through the environment details page or the admin API response rather than assuming the string is identical across tenants.
Map the Tool to the Exact Field It Reads
Different tools read different fields, and knowing which one your error came from cuts the diagnosis in half. The table below maps the most common surfaces to the value each one actually consumes.
| Tool or surface | Field it reads | What causes the error |
|---|---|---|
| Power Automate custom connector | Environment unique name used to build the host | ~default or any non-alphanumeric character in the unique name |
| Power Apps maker portal connection | Environment selected for the connection | Default environment alias leaking into the derived host |
| Power Platform CLI environment commands | --environment value, accepts ID or URL | Passing the display name or the raw alias instead of the ID |
| Admin center environment list | Display name and unique name shown side by side | Reading only the display name and assuming it matches the identifier |
| Web API direct call | Full resource URL you typed | Constructing the URL from the default alias by hand |
The row that catches most people is the CLI one. The command line accepts an environment ID, a full URL, or a name, and it resolves them in that order of reliability. A display name that contains a space or a special character will fail even when the environment itself is healthy.
Pick the resolution path that returns an ID first. That value is a GUID-shaped identifier with no characters that can fail host-name validation, and every tool that accepts an environment reference will accept it.
Inspect the Identifier Before You Change Anything
Read the actual identifier for the environment you intend to use. In the Power Platform admin center, open Environments, select the environment, and look at the details panel, where the unique name and the environment ID appear separately. Copy the unique name character by character.
Next, compare that string against the display name. If they differ by more than case, note the difference, because the unique name is what the endpoint generator uses. A display name like "Sales Production" can hide a unique name like sales-prod-3f2a, which is perfectly valid.
Then check for the specific failing set. Scan for a tilde, a space, an underscore, a period, or any character outside a-z, 0-9, and -. If you find one, you have located the failure without touching a single setting.
If the details panel shows a clean unique name but the error persists, the tool is reading a cached value. Clear the connection, reauthenticate, and regenerate. A stale environment reference survives sign-out in some clients.
Choose Between Four Fix Paths
Four legitimate fixes exist, and each suits a different situation. The table compares them on the dimensions that decide the choice.
| Fix path | Effort | Fits this case | Limitation |
|---|---|---|---|
| Target a non-default environment with a clean unique name | Low | Any new build | Default environment resources must be migrated |
| Reference the environment by ID instead of name | Low | CLI and API work | Some UI pickers do not accept IDs |
| Create a new environment with a compliant name | Medium | Long-term hygiene | Consumes environment capacity in the tenant |
| Rename the environment unique name | High, sometimes impossible | Custom environments only | Default environment cannot be renamed this way |
The fastest reliable fix is the second row. Switch every reference from the name to the environment ID, and the tilde never enters the string. Use the first row when you are starting fresh and can choose where the work lives.
Renaming deserves a caution. Microsoft's environment management documentation treats the unique name as part of the environment's identity, and renaming a Dataverse-backed environment is not a supported routine operation through the admin center. Do not plan a rename unless the environment is non-default and the admin surfaces actually offer the change.
Creating a new environment is the cleanest long-term answer when you control the tenant. Name it with lowercase letters, digits, and single hyphens, keep the name short, and avoid anything that resembles a reserved word.
Step-by-Step: Regenerate the Endpoint Against a Compliant Environment
Follow these steps in order. The sequence matters because a cached reference at step 1 will make every later step look broken.
1: In the Power Platform admin center, open Environments and copy the environment ID for a non-default environment whose unique name contains only letters, digits, and dashes. 2: In the maker portal, open the connection or custom connector that failed, remove the existing environment binding, and save. 3: Reopen the connector, paste the environment ID into the environment field, and confirm the derived host shown on screen matches your expected yourorg.crm.dynamics.com pattern. 4: Regenerate the API endpoint and confirm the operation list loads rather than the validation error. 5: Test one read operation against a known record before republishing the connector to any app.
If step 3 still shows the tilde, you pasted a display name rather than an ID. If step 4 succeeds but step 5 returns a 401, the fix worked and the remaining problem is consent for the connection, not the identifier.
If step 5 returns a 404, the environment exists but the table or record you targeted does not, and the endpoint itself is fine. Any error other than the original host-name message means you moved past this failure.
Rename or Replace a Non-Compliant Environment Identifier
For custom environments with a bad unique name, check the rename surface before planning anything. Open the environment in the admin center, look for the edit option next to the name, and read exactly which field it changes. Many tenants expose a display-name edit and not a unique-name edit, and those are not the same field.
When a true rename is available, the operation is asynchronous. Microsoft's environment lifecycle behavior means the change propagates through the service over time, and connectors that cached the old reference keep failing until you reauthenticate them. Plan a window where the environment is not serving production traffic.
The default environment is the exception that proves the rule. Its alias is fixed, so plan around it rather than against it. Create a dedicated environment, name it correctly from birth, and treat the default environment as a scratch pad.
Naming rules to hold to: lowercase letters, digits, and single hyphens; no leading or trailing hyphen; keep it under the host-label length limit; avoid names that collide with tenant-reserved words. Getting this right at creation costs seconds and avoids this entire class of error later.
Validate the Generated Endpoint Without a Publish
You do not need to publish anything to confirm the fix. The environment details page in the admin center lists the organization URL, and that URL is the host the endpoint generator should construct. Compare the two strings character for character.
Do the comparison in a way that exposes invisible problems. A trailing space or a lookalike character from a copy-paste can fail validation while looking identical on screen. Paste the identifier into a plain text editor with visible characters enabled, or compare string lengths as a sanity check.
For Web API work, the test call is a GET against the WhoAmI function on the organization URL, which returns the calling user's identity when authentication is correct. A 200 with a user ID confirms the URL, the token, and the environment all line up. A 401 confirms the URL works and the token does not.
Publish last. Connectors that go live with a validated endpoint and a tested operation cost you one test call. Connectors that go live with an unvalidated one cost a support ticket from every user who hits the broken operation first.
The ~default Trap in Custom Connectors and the Web API
Custom connectors are where this error causes the most wasted time, because the connector definition stores the environment reference inside the OpenAPI host and base path. If that stored value contains the tilde, every export and reimport of the connector carries the defect forward. Rewrite the base URL in the definition itself, not only in the connection dialog.
The Web API path has its own version of the trap. Anyone who hand-builds a call from the default environment's alias produces a URL with a tilde in the host, and the service rejects it at the network layer. The service never tells you the identifier was invalid, only that the request failed. Build Web API URLs from the organization URL the admin center reports.
Watch for scripts that hardcode the alias in a configuration file. A pipeline that generates endpoint configuration from a tenant inventory may pick up ~default for the default environment row and distribute it to every downstream tool. Fix the inventory, then fix the consumers.
If you support multiple tenants, run the check as a preflight step. Any environment reference containing a character outside the allowed set should fail the build before a deployment starts.
Preventing the Error with Naming and Connection Governance
Set the rule once and enforce it at environment creation. A naming convention of lowercase letters, digits, and hyphens, applied by whoever provisions environments, eliminates the error category permanently. Document it where environment requests are filed, not in a wiki nobody reads.
Prefer environment IDs in every automated reference. Names are for humans, IDs are for machines, and IDs never fail host-name validation. This one habit removes the tilde from any script you write.
Keep the default environment out of production paths. Use it for personal testing and sandbox work, and never bind a production connector to it. Microsoft's own guidance on environment strategy separates personal productivity from managed environments for good reasons that go beyond this error.
Audit existing connections on a schedule. List every connector, dump its stored environment reference, and flag any value containing a non-compliant character. Catching a stale reference during an audit is cheaper than catching it during an incident.
FAQ
Does the ~default error mean my environment is broken?
No. The environment works fine for apps and flows; only endpoint generation fails, because that path derives a host name from the alias. You can build and run resources in the default environment without ever seeing this message. Treat it as a naming constraint on one operation, not a health signal.
Can I rename the default environment to remove the tilde?
In practice, no. The default environment's unique name is tenant-fixed in the admin surfaces Microsoft documents, and the edit option changes the display name rather than the identifier. Plan around the alias by targeting a dedicated environment for anything that needs a generated endpoint.
Why does the error still appear after I picked a different environment?
The tool is probably reading a cached reference from the connection rather than the picker. Remove the connection, reauthenticate, and regenerate. If it persists, confirm whether your tool accepts an ID; paste the environment ID directly and compare the derived host on screen.
Which characters are allowed in an environment identifier?
Lowercase letters, digits, and hyphens, matching the DNS label rules in RFC 1123. Uppercase is tolerated in display names but normalize to lowercase for safety. Spaces, underscores, periods, tildes, accented letters, and non-Latin characters all fail the same check.
Is passing the environment ID a permanent fix or a workaround?
Permanent for the tools that accept it. The environment ID is a stable identifier that never enters host-name validation, so references built on it cannot fail this way. Keep using IDs in scripts and connector definitions even after you clean up naming.
What happens if I ignore the error and hardcode the URL anyway?
The request fails at the network layer without a useful message. The service sees a host containing a tilde and rejects the connection before authentication is evaluated, so hardcoding produces failures that look like outages rather than configuration errors. Build URLs from the organization URL in the admin center.
Does this error affect every environment or only tenants created years ago?
Custom environments are unaffected unless their unique name breaks the character rule. The failure concentrates on the default environment, which every tenant has, so new and old tenants alike can hit it the moment a connector binds to that alias. New tenants are not immune, only better positioned to start clean.
How long does a rename or new environment take to propagate?
Expect minutes to hours, not seconds. Connector references cached before the change continue to fail until reauthenticated, so plan a maintenance window and re-test with a WhoAmI call before resuming traffic. Creation is faster than rename because no identity change is involved.