Custom outpost troubleshooting
Diagnose and fix custom outpost failures, including custom networking (BYON), your own Azure app registration (BYOA), and Egress routing off, during Terraform plan, Terraform apply, or runtime.
Use this topic to diagnose failures during and after the deployment of a custom outpost. Each table lists a symptom or error message, when it appears (plan, apply, or runtime), and the fix. For issues that apply to all outposts, see Outpost troubleshooting.
Custom networking (BYON) troubleshooting
Most failures with custom networking are network misconfigurations. For the plan-time rules, see the Terraform validation reference.
Custom networking: AWS
The following table covers the most common AWS failures with custom networking.
Each region in byon_config must have at least 1 zone
plan
Add at least one AZ subnet to each region in the byon_config block.
See Validate your network and proxy values for the AWS block shape.
Scanner has no internet egress
runtime
The NAT model was chosen but no NAT Gateway or route to the internet exists, or the proxy model was chosen but the proxy is unreachable.
Provision the chosen outbound path, and confirm the outbound-model decision matches the network you actually operate.
proxy_config.enabled can only be true when byon_config is set
plan
The outbound proxy is valid only with custom networking.
Either provide a byon_config block, or remove proxy_config.enabled = true.
When proxy_enabled is true in BYON mode, proxy_host must resolve to a literal IPv4 address for the scanner SG egress CIDR
plan
The proxy address uses a hostname or an IPv6 address. On AWS, the scanner security group allows egress to the proxy as a /32 CIDR, so the host must be an IPv4 address.
Enter the proxy's IPv4 address in the Proxy address field, and download and run the template again. An http:// or https:// prefix is allowed.
Custom networking: Azure
The following table covers the most common Azure failures with custom networking.
subnet_id ... belongs to VNet '<x>', but virtual_network_id points to VNet '<y>'
plan
The subnet is not inside the virtual network you named.
Fix one of the ARM IDs so they reference the same virtual network.
403 LinkedAuthorizationFailed when the scanner NIC joins the subnet
apply
The Terraform runner lacks User Access Administrator at the virtual network's scope, and in the virtual network's subscription if different.
Grant it and rerun terraform apply.
keys(byon_config) must exactly equal enabled_locations
plan
Regions with your network and regions with a Cortex XSIAM network were mixed.
Displays as a warning.
Make the set of regions in byon_config exactly equal to the enabled locations.
Proxy validation errors (host must be non-empty, ca_cert_content must be base64, both proxy_username and proxy_password must be provided)
plan
The proxy_config shape is invalid.
Fix proxy_config per Validate your network and proxy values. Pass credentials via -var. Encode the CA certificate with cat ca.pem
Terraform error indicating the virtual network (VNet) or subnet could not be found (for example, ResourceNotFound or 404 Not Found).
plan
Verify that the VNet and subnet resource IDs provided in your byon_config are correct, that they currently exist in your Azure environment, and that the Terraform runner has the required permissions to read them.
Terraform validation error indicating that the subnet does not belong to the provided virtual network.
plan
Check your byon_config to ensure the subnet specified is actually a part of the provided VNet. The fully qualified subnet ID string must correctly contain the VNet's name in its path.
Custom networking: GCP
The following table covers the most common GCP failures with custom networking.
byon_config.subnets must contain at least one region
plan
The subnets map is empty.
Add at least one region to byon_config.subnets.
byon_config.compute_vpc_id must not be empty
plan
The VPC self-link was not set.
Set compute_vpc_id to your VPC self-link.
Scanner cannot reach Google APIs or Cloud SQL
runtime
Your firewall (which you own with custom networking) is blocking egress.
Allow the destinations in the GCP section of the Outbound allow-list reference, or route them through your proxy.
proxy_config.enabled can only be true when byon_config is set
plan
The outbound proxy is valid only with custom networking.
Either provide a byon_config block, or remove proxy_config.enabled = true.
Egress routing off troubleshooting
When Outpost networking is set to Egress routing off, scanner VMs have no outbound internet access, so some capabilities do not work by design.
Vulnerability findings are not updated with new CVEs or advisories.
Vulnerability feeds cannot be downloaded. Scanners run with the last cached data.
If you need current vulnerability data, change Outpost networking to Default or Custom.
Images in Docker Hub, GHCR, Quay, MCR, or other public registries are not scanned.
Public registries cannot be reached.
Scan the images from a private registry that the outpost can reach, or change Outpost networking.
SaaS DSPM sources are not scanned.
Managed database connectors that require outbound access to SaaS endpoints do not run.
Change Outpost networking to Default or Custom.
Threat intelligence and IOC enrichment are not updated.
ATI feeds cannot be updated.
Change Outpost networking to Default or Custom.
Bring your own app registration (BYOA) troubleshooting
The following errors can occur when you deploy an Azure outpost with your own app registration. They can appear, for example, if you created the app registration, service principal, and user-assigned managed identities (UAMIs) manually in the Azure portal instead of with the helper shell script.
Use the following table to identify the symptom and apply the resolution.
Single-tenant app registration
Error: ... sign_in_audience must be 'AzureADMultipleOrgs' ...
Plan
Recreate the app registration as a multi-tenant application.
The Azure portal defaults to single-tenant ("this org only").
Run this command:
az ad app create --display-name <name> --sign-in-audience AzureADMultipleOrgs
Incorrect service principal ID
Error: ... customer_sp_object_id ... is the SP of a different AppReg ...
Plan
An incorrect service principal object ID was provided.
Retrieve the correct ID by running:
az ad sp show --id <CUSTOMER_APP_CLIENT_ID> --query id -o tsv
Update the customer_sp_object_id variable in your tfvars file.
Missing Terraform runner ownership
Error: Warning: The Terraform runner ... is NOT listed as an owner of the BYO App Registration ...
Plan
The Terraform runner must be added as an owner of the app registration.
Without this, the deployment fails with an "Insufficient privileges" error when attempting to create the first federated identity credential (FIC).
Run:
az ad app owner add --id <APP_ID> --owner-object-id <TF_RUNNER_OBJ_ID>
Disabled service principal
Error: ... Customer SP ... is disabled in Entra ...
Plan
The service principal is disabled.
Re-enable it by running:
az ad sp update --id <SP_OBJ_ID> --set accountEnabled=true
Alternatively, toggle it in the Azure portal under Enterprise applications > [Your SP] > Properties.
Cross-subscription UAMI
Error: ... Customer UAMI ... lives in subscription <X> but the outpost is being deployed to <Y> ...
Plan
Cross-subscription UAMIs are not supported because the Azure Instance Metadata Service (IMDS) only returns tokens for local identities.
Recreate the UAMI in the outpost's subscription and update customer_uami_*_id in your tfvars file.
Cross-tenant UAMI
Error: ... Customer UAMI ... lives in tenant <X> but the outpost subscription is in tenant <Y> ...
Plan
Cross-tenant UAMIs are not supported. Recreate the UAMI in the correct Entra ID tenant to match the outpost subscription.
Duplicate UAMI IDs
Error: ... All 5 customer UAMI IDs must be distinct ...
Plan
Duplicate UAMI IDs were provided. The error message lists all 5 IDs. Replace the duplicates with the correct, distinct UAMI IDs and rerun Terraform.
Insufficient privileges for FIC
Error: Error: creating Federated Identity Credential ... Insufficient privileges to complete the operation
Apply
App registration owner permissions are missing for the Terraform runner.
Verify ownership by running az ad app owner list --id <APP_ID>.
Add the owner by running:
az ad app owner add --id <APP_ID> --owner-object-id <TF_RUNNER>
Stale federated credential
Error: Another object with the same value for property federatedIdentityCredentials/<name> already exists
Apply
A stale FIC exists from a previous deployment attempt or manual portal entry.
List existing credentials using az ad app federated-credential list --id <APP_ID> -o table.
Delete the conflicting one with az ad app federated-credential delete --id <APP_ID> --federated-credential-id <NAME>.
Rerun the deployment.
Subject does not exist (replication lag)
Error: 400 BadRequest: Subject does not exist in directory.
Apply
The UAMI was created very recently, and it has not yet replicated across Entra ID.
Wait 30 to 60 seconds and rerun terraform apply.
Verify the subject exists with az ad sp show --id <UAMI_PRINCIPAL_ID>.
Accidental UAMI deletion
Error: terraform destroy deleted my customer-created UAMIs!
Destroy
The UAMIs were incorrectly placed inside the outpost's Cortex-managed resource group. Terraform deletes UAMIs placed inside the outpost's Cortex-managed resource group during a destroy operation. Recreate the UAMIs in a customer-owned resource group outside of the outpost boundaries and re-onboard.
Last updated
Was this helpful?
