Troubleshooting#
This article provides troubleshooting instructions for common errors.
Bicep compile errors#
When expanding Bicep source files you may get an error including a BCPnnn code similar to the following:
Error
Exception calling "GetResources" with "3" argument(s): "Bicep (0.14.46) compilation of '
This error is raised when Bicep fails to compile a source file. To resolve this issue:
- You may need to update your Bicep source file before PSRule can expand it. Use guidance from the Bicep error message to help resolve the issue.
- Check that you are using a version of Bicep that supports the Bicep features you are using.
It may not always be clear which version of Bicep CLI PSRule for Azure is using if you have multiple versions installed.
Using the Bicep CLI via
az bicep
is not the default, and you may need to set additional options to use it.
Tip
From PSRule for Azure v1.25.0 you can configure the minimum version of Bicep CLI required. If an earlier version is detected, PSRule for Azure will generate an error. See Configuring minimum version for details on how to configure this option.
Bicep version#
When expanding Bicep source files you may get an error relating to the Bicep version you have installed. For example if you attempt to use a Bicep feature that is not supported by the version used by PSRule for Azure.
PSRule for Azure uses the Bicep CLI installed on your machine or CI worker.
By default, the Bicep CLI binary will be selected by your PATH
environment variable.
Optionally you can configure an alternative Bicep CLI binary to use by either:
- By path — Set the PSRULE_AZURE_BICEP_PATH environment variable to the specified binary path.
- From Azure CLI — Set the PSRULE_AZURE_BICEP_USE_AZURE_CLI environment variable to
true
.
For more details on installing and configuring the Bicep CLI, see Setup Bicep.
Bicep compilation timeout#
When expanding Bicep source files you may get an error similar to the following:
Error
Bicep (0.4.1124) compilation of 'C:\temp\deploy.bicep' failed with: Bicep compilation hasn't completed within the timeout window. This can be caused by errors or warnings. Check the Bicep output by running bicep build and addressing any issues.
This error is raised when Bicep takes longer then the timeout to build a source file. The default timeout is 5 seconds.
You can take steps to reduce your code complexity and reduce the time a build takes by:
- Removing unnecessary nested
module
calls. - Cache bicep modules restored from a registry in continuous integration (CI) pipelines.
To increase the timeout value, set the AZURE_BICEP_FILE_EXPANSION_TIMEOUT
configuration option.
See Bicep compilation timeout for details on how to configure this option.
No rules or no Azure resources are found#
There is a few common causes of this issue including:
- Check input format — PSRule for Azure must discover files to expand them.
- When running PSRule for Azure using GitHub Actions or the Azure Pipelines extension:
- Your pipeline must be set to
inputType: repository
, which is the default value. - PSRule for Azure will not work with
inputType
set toinputPath
. - You may have set this parameter because you wanted to use the
inputPath
parameter. Setting theinputType
is not a requirement for using theinputPath
parameter. TheinputPath
parameter can be used independently.
- Your pipeline must be set to
- When running PSRule for Azure from PowerShell:
- Your command-line must use the
-Format File
parameter. - Your command-line must use the
-InputPath
or-f
parameter followed by a file or directory path. - For example:
Assert-PSRule -Module PSRule.Rules.Azure -Format File -f 'modules/'
.
- Your command-line must use the
- When running PSRule for Azure using GitHub Actions or the Azure Pipelines extension:
- Check expansion is enabled — Expansion must be enabled to analyze Azure Infrastructure as Code. See using templates and using Bicep source for details on how to enable expansion.
- Check parameter files are linked — Parameter files must be linked to ARM templates or Bicep source files. See using templates for details on how to link using metadata or naming convention.
Note
If your pipeline is still not finding any Azure resources, please join or start a discussion.
Custom rules are not running#
There is a few common causes of this issue including:
- Check rule path — By default, PSRule will look for rules in the
.ps-rule/
directory. This directory is the root for your repository or the current working path by default. On case-sensitive file systems such as Linux, this directory name is case-sensitive. See Storing and naming rules for more information. - Check file name suffix — PSRule only looks for files with the
.Rule.ps1
,.Rule.yaml
, or.Rule.jsonc
suffix. On case-sensitive file systems such as Linux, this file suffix is case-sensitive. See Storing and naming rules for more information. - Check binding configuration — PSRule uses binding to work out which property to use for a resource type.
To be able to use the
-Type
parameter ortype
properties in rules definitions, binding must be set. This is automatically configured for PSRule for Azure, however must be set inps-rule.yaml
for custom rules. See binding type for more information. - Check modules — PSRule for Azure is responsible for expanding Azure resources from Infrastructure as Code.
Expansion occurs automatically in memory when enabled.
For this to work, the module
PSRule.Rules.Azure
must be run with any custom rules. See using templates and using Bicep source for details on how to enable expansion. - Check include local option — When running PSRule for Azure with a baseline.
Baselines such as quarterly baselines may use filters to limit the rules that are included.
As a result, custom rules may not be included.
To include custom rules set the Rule.IncludeLocal option to
true
. See Including custom rules for more information.
Tip
You may be able to use git mv
to change the case of a file if it is committed to the repository incorrectly.
Parameter file warns of metadata property#
You may find while editing a .json
parameter file the root metadata
property is flagged with a warning.
Warning
The property 'metadata' is not allowed.
{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"metadata": {
"template": "./storage.template.json"
},
"parameters": {
}
}
This doesn't affect the workings of the parameter file or deployment.
The reason for the warning is that the metadata
property has not been added to the parameter file JSON schema.
However, the top level metadata
property is ignored by Azure Resource Manager when deploying a template.
An earlier version of Az.Accounts is imported#
When running PSRule for Azure in Azure DevOps within the AzurePowerShell@5
task,
you may see the following error.
Error
This module requires Az.Accounts version 2.8.0. An earlier version of Az.Accounts is imported in the current PowerShell session. Please open a new session before importing this module. This error could indicate that multiple incompatible versions of the Azure PowerShell cmdlets are installed on your system. Please see https://aka.ms/azps-version-error for troubleshooting information.
This error is raised by a chained dependency failure importing a newer version of Az.Accounts
.
To avoid this issue attempt to install the exact versions of Az.Resources
.
In the AzurePowerShell@5
task before installing PSRule.
Install-Module Az.Resources -RequiredVersion '5.6.0' -Force -Scope CurrentUser
From PSRule for Azure v1.16.0, Az.Accounts
and Az.Resources
are no longer installed as dependencies.
When using export commands from PSRule, you may need to install these modules.
To install these modules, use the following PowerShell command:
Install-Module Az.Resources -Force -Scope CurrentUser
Could not load file or assembly YamlDotNet#
PSRule >=1.3.0 uses an updated version of the YamlDotNet library. The PSRule for Azure <1.3.1 uses an older version of this library which may conflict.
To avoid this issue:
- Update to the latest version and use PSRule for Azure >=1.3.1 with PSRule >=1.3.0.
- Alternatively, when using PSRule for Azure <1.3.1 use PSRule =1.2.0.
To install the latest module version of PSRule use the following commands:
Install-Module -Name PSRule.Rules.Azure -MinimumVersion 1.3.1 -Scope CurrentUser -Force;
For the PSRule GitHub Action, use >=1.4.0.
- name: Run PSRule analysis
uses: microsoft/ps-rule@v2.8.1