Connection References and Environment Variables

The import into the test environment went through, and so did the one into production. Still, the next morning the flows stand still, or they write into the SharePoint library of the development environment. Behind such reports there are almost always the same two building blocks: connection references and environment variables. Both exist so that a solution runs with the right settings in every environment. But both cause errors if you treat them like normal components.

What the two building blocks do

A connection reference is a placeholder for a connection. Power Automate flows bind to this reference and not directly to a connection. The actual connection, meaning the stored sign-in, belongs to the environment and does not travel along. During the import, each reference is assigned a connection of the target environment. Only then can flows be turned on at all (Microsoft Learn: Use a connection reference in a solution).

An environment variable separates a setting from the components that use it, for example an address or a threshold. It consists of the definition with an optional default value and a current value that is set per environment.

Typical mistakes with connection references

No connection in the target environment. If a reference has no connection yet, the flow arrives but stays turned off until someone assigns the connection. This is usually noticed only when a process fails to happen.

The wrong person imports. Whoever turns on a flow must own all connections in it or have them shared. Otherwise the flow cannot be activated. If an administrator imports with connections that belong to a colleague, they face exactly this error. Service accounts that own the connections avoid the problem.

Custom connector in the same solution. Microsoft states explicitly that custom connectors must be imported in a separate solution before the connection references and flows. If they sit together in one solution, this causes problems during the import according to Microsoft.

Disabled or orphaned references. A disabled reference paralyzes all flows that use it. A reference that no flow in the solution uses is often a leftover. But it may also be needed by a canvas app or another solution. So check this before deleting.

Values versus default values

With environment variables, the most common mistake lies in the difference between default value and current value. The default value belongs to the definition and may travel with the solution. The current value applies to one environment. If it is set, it always wins, even when a default value exists (Microsoft Learn: Environment variables).

The reason lies in the export. If a current value was set in the development environment and is part of the solution, it travels along. It then overwrites the correct setting in the target environment. The import reports no error. Microsoft therefore recommends not including the current value in the solution. That means: the definition belongs in, and the value is set for the target environment during deployment. Before the export, you can take the value out of the solution with "Remove from this solution".

Two consequences are less well known. Once the value has arrived in the target environment with a managed solution, it disappears there only when a new version without the value is imported as an upgrade (not as an update!). And in a managed solution, you see the current value only through the default solution. Whoever looks into the managed solution while troubleshooting may not see it.

The opposite case also occurs: a required variable with no default value and no value supplied can become a problem. The import dialog does ask for it. But in an automated deployment such values are easily forgotten. Flows and apps then work only when someone adds the value by hand.

The deployment settings file

For automated deployments there is a file that records both in advance: the connection of the target environment for each connection reference, and the value for each environment variable (Microsoft Learn: Prepopulate connection references and environment variables). The Power Platform CLI generates the template from the solution export:

pac solution create-settings --solution-zip MySolution.zip --settings-file Production.json

You fill in the empty fields once per target environment: the connection ID and the value of the variable. During the import, you pass the file along, either with the Power Platform Build Tools or with "pac solution import" and the parameter "--settings-file". The files for each environment belong in source control, so it stays traceable which environment gets which values. Secrets such as passwords do not belong there. For those there are environment variables of type secret, backed by Azure Key Vault.

You should know one limit. If a new connection reference or variable enters the solution, it is missing from the file until someone adds it. So the file is not finished once. It grows with the solution.

Check before the import

Three questions catch most of these errors before they reach production. Does the solution contain current values for environment variables, and is that intended? Are there required variables without any value? For every connection reference, is it clear which connection it gets in the target environment, and who owns it?

The first two can be answered from the solution export, as can disabled and unused connection references (D365 Audit checks these, for example). The third question concerns the environment and remains manual work. If you run a pipeline, build the export check in as a step before the import. Then a development value that came along shows up in the pipeline and not only in production. More about the other import errors is in Common deployment mistakes in Dynamics 365 solutions. A checklist you can tick off is in Quality checks before deployment.