> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xsiam/configure-cortex-xsiam/cortex-xsiam-data-sources/cloud-service-provider-csp-onboarding/outpost-onboarding/working-with-custom-outposts/custom-outpost-troubleshooting.md).

# 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](https://cortex-docs.paloaltonetworks.com/cortex-xsiam/configure-cortex-xsiam/cortex-xsiam-data-sources/cloud-service-provider-csp-onboarding/outpost-onboarding/outpost-troubleshooting.md).

## Custom networking (BYON) troubleshooting

{% hint style="info" %}
**Note:** This section applies only to custom outposts where **Outpost networking** is set to **Custom**. If you chose **Default** or **Egress routing off**, skip this section.
{% endhint %}

Most failures with custom networking are network misconfigurations. For the plan-time rules, see the [Terraform validation reference](https://cortex-docs.paloaltonetworks.com/cortex-xsiam/configure-cortex-xsiam/cortex-xsiam-data-sources/cloud-service-provider-csp-onboarding/outpost-onboarding/working-with-custom-outposts/custom-networking-byon/terraform-validation-reference.md).

### Custom networking: AWS

The following table covers the most common AWS failures with custom networking.

| Symptom or error message                                                                                                    | When    | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Each region in byon_config must have at least 1 zone`                                                                      | plan    | <p>Add at least one AZ subnet to each region in the <code>byon\_config</code> block.</p><p><br></p><p>See <a href="https://cortex-docs.paloaltonetworks.com/cortex-xsiam/configure-cortex-xsiam/cortex-xsiam-data-sources/cloud-service-provider-csp-onboarding/outpost-onboarding/working-with-custom-outposts/custom-networking-byon/validate-your-network-and-proxy-values.md">Validate your network and proxy values</a> for the AWS block shape.</p> |
| Scanner has no internet egress                                                                                              | runtime | <p>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.</p><p><br></p><p>Provision the chosen outbound path, and confirm the outbound-model decision matches the network you actually operate.</p>                                                                                                                                                                    |
| `proxy_config.enabled can only be true when byon_config is set`                                                             | plan    | <p>The outbound proxy is valid only with custom networking.</p><p><br></p><p>Either provide a <code>byon\_config</code> block, or remove <code>proxy\_config.enabled = true</code>.</p>                                                                                                                                                                                                                                                                   |
| `When proxy_enabled is true in BYON mode, proxy_host must resolve to a literal IPv4 address for the scanner SG egress CIDR` | plan    | <p>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.</p><p><br></p><p>Enter the proxy's IPv4 address in the <strong>Proxy address</strong> field, and download and run the template again. An <code>http\://</code> or <code>https\://</code> prefix is allowed.</p>                                                                |

### Custom networking: Azure

The following table covers the most common Azure failures with custom networking.

| Symptom or error message                                                                                                                          | When  | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `subnet_id ... belongs to VNet '<x>', but virtual_network_id points to VNet '<y>'`                                                                | plan  | <p>The subnet is not inside the virtual network you named.</p><p><br></p><p>Fix one of the ARM IDs so they reference the same virtual network.</p>                                                                                                                                                                                                                                                                                                                                                                             |
| `403 LinkedAuthorizationFailed` when the scanner NIC joins the subnet                                                                             | apply | <p>The Terraform runner lacks User Access Administrator at the virtual network's scope, and in the virtual network's subscription if different.</p><p><br></p><p>Grant it and rerun <code>terraform apply</code>.</p>                                                                                                                                                                                                                                                                                                          |
| `keys(byon_config) must exactly equal enabled_locations`                                                                                          | plan  | <p>Regions with your network and regions with a Cortex XSIAM network were mixed.</p><p>Displays as a warning.</p><p>Make the set of regions in <code>byon\_config</code> exactly equal to the enabled locations.</p>                                                                                                                                                                                                                                                                                                           |
| Proxy validation errors (`host` must be non-empty, `ca_cert_content` must be base64, both `proxy_username` and `proxy_password` must be provided) | plan  | <p>The <code>proxy\_config</code> shape is invalid.</p><p><br></p><p>Fix <code>proxy\_config</code> per <a href="https://cortex-docs.paloaltonetworks.com/cortex-xsiam/configure-cortex-xsiam/cortex-xsiam-data-sources/cloud-service-provider-csp-onboarding/outpost-onboarding/working-with-custom-outposts/custom-networking-byon/validate-your-network-and-proxy-values.md">Validate your network and proxy values</a>. Pass credentials via <code>-var</code>. Encode the CA certificate with <code>cat ca.pem</code></p> |
| 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.

| Symptom or error message                                        | When    | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `byon_config.subnets must contain at least one region`          | plan    | <p>The subnets map is empty.</p><p><br></p><p>Add at least one region to <code>byon\_config.subnets</code>.</p>                                                                                                                                                                                                                                                                                                                                                                       |
| `byon_config.compute_vpc_id must not be empty`                  | plan    | <p>The VPC self-link was not set.</p><p><br></p><p>Set <code>compute\_vpc\_id</code> to your VPC self-link.</p>                                                                                                                                                                                                                                                                                                                                                                       |
| Scanner cannot reach Google APIs or Cloud SQL                   | runtime | <p>Your firewall (which you own with custom networking) is blocking egress.</p><p><br></p><p>Allow the destinations in the GCP section of the <a href="https://cortex-docs.paloaltonetworks.com/cortex-xsiam/configure-cortex-xsiam/cortex-xsiam-data-sources/cloud-service-provider-csp-onboarding/outpost-onboarding/working-with-custom-outposts/custom-networking-byon/outbound-allow-list-reference.md">Outbound allow-list reference</a>, or route them through your proxy.</p> |
| `proxy_config.enabled can only be true when byon_config is set` | plan    | <p>The outbound proxy is valid only with custom networking.</p><p><br></p><p>Either provide a <code>byon\_config</code> block, or remove <code>proxy\_config.enabled = true</code>.</p>                                                                                                                                                                                                                                                                                               |

## 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.

| Symptom                                                                            | Cause                                                                                  | Fix                                                                                                   |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 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

{% hint style="info" %}
**Note:** This section applies only to Azure outposts where you turn on **Bring Your Own App Registration**. If Cortex creates the app registration for you, skip this section.
{% endhint %}

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.

<table><thead><tr><th>Symptom / error message</th><th width="130.47265625">Terraform deployment phase</th><th>Resolution</th></tr></thead><tbody><tr><td><strong>Single-tenant app registration</strong><br><br><em>Error:</em> <code>... sign_in_audience must be 'AzureADMultipleOrgs' ...</code></td><td>Plan</td><td>Recreate the app registration as a multi-tenant application.<br><br>The Azure portal defaults to single-tenant ("this org only").<br><br>Run this command:<br><br><code>az ad app create --display-name &#x3C;name> --sign-in-audience AzureADMultipleOrgs</code></td></tr><tr><td><strong>Incorrect service principal ID</strong><br><br><em>Error:</em> <code>... customer_sp_object_id ... is the SP of a different AppReg ...</code></td><td>Plan</td><td>An incorrect service principal object ID was provided.<br><br>Retrieve the correct ID by running:<br><br><code>az ad sp show --id &#x3C;CUSTOMER_APP_CLIENT_ID> --query id -o tsv</code><br><br>Update the <code>customer_sp_object_id</code> variable in your <code>tfvars</code> file.</td></tr><tr><td><strong>Missing Terraform runner ownership</strong><br><br><em>Error:</em> <code>Warning: The Terraform runner ... is NOT listed as an owner of the BYO App Registration ...</code></td><td>Plan</td><td>The Terraform runner must be added as an owner of the app registration.<br><br>Without this, the deployment fails with an "Insufficient privileges" error when attempting to create the first federated identity credential (FIC).<br><br>Run:<br><br><code>az ad app owner add --id &#x3C;APP_ID> --owner-object-id &#x3C;TF_RUNNER_OBJ_ID></code></td></tr><tr><td><strong>Disabled service principal</strong><br><br><em>Error:</em> <code>... Customer SP ... is disabled in Entra ...</code></td><td>Plan</td><td>The service principal is disabled.<br><br>Re-enable it by running:<br><br><code>az ad sp update --id &#x3C;SP_OBJ_ID> --set accountEnabled=true</code><br><br>Alternatively, toggle it in the Azure portal under <strong>Enterprise applications</strong> > <strong>[Your SP]</strong> > <strong>Properties</strong>.</td></tr><tr><td><strong>Cross-subscription UAMI</strong><br><br><em>Error:</em> <code>... Customer UAMI ... lives in subscription &#x3C;X> but the outpost is being deployed to &#x3C;Y> ...</code></td><td>Plan</td><td>Cross-subscription UAMIs are not supported because the Azure Instance Metadata Service (IMDS) only returns tokens for local identities.<br><br>Recreate the UAMI in the outpost's subscription and update <code>customer_uami_*_id</code> in your <code>tfvars</code> file.</td></tr><tr><td><strong>Cross-tenant UAMI</strong><br><br><em>Error:</em> <code>... Customer UAMI ... lives in tenant &#x3C;X> but the outpost subscription is in tenant &#x3C;Y> ...</code></td><td>Plan</td><td>Cross-tenant UAMIs are not supported.<br><br>Recreate the UAMI in the correct Entra ID tenant to match the outpost subscription.</td></tr><tr><td><strong>Duplicate UAMI IDs</strong><br><br><em>Error:</em> <code>... All 5 customer UAMI IDs must be distinct ...</code></td><td>Plan</td><td>Duplicate UAMI IDs were provided.<br><br>The error message lists all 5 IDs.<br><br>Replace the duplicates with the correct, distinct UAMI IDs and rerun Terraform.</td></tr><tr><td><strong>Insufficient privileges for FIC</strong><br><br><em>Error:</em> <code>Error: creating Federated Identity Credential ... Insufficient privileges to complete the operation</code></td><td>Apply</td><td>App registration owner permissions are missing for the Terraform runner.<br><br>Verify ownership by running <code>az ad app owner list --id &#x3C;APP_ID></code>.<br><br>Add the owner by running:<br><br><code>az ad app owner add --id &#x3C;APP_ID> --owner-object-id &#x3C;TF_RUNNER></code></td></tr><tr><td><strong>Stale federated credential</strong><br><br><em>Error:</em> <code>Another object with the same value for property federatedIdentityCredentials/&#x3C;name> already exists</code></td><td>Apply</td><td>A stale FIC exists from a previous deployment attempt or manual portal entry.<br><br>List existing credentials using <code>az ad app federated-credential list --id &#x3C;APP_ID> -o table</code>.<br><br>Delete the conflicting one with <code>az ad app federated-credential delete --id &#x3C;APP_ID> --federated-credential-id &#x3C;NAME></code>.<br><br>Rerun the deployment.</td></tr><tr><td><strong>Subject does not exist (replication lag)</strong><br><br><em>Error:</em> <code>400 BadRequest: Subject does not exist in directory.</code></td><td>Apply</td><td>The UAMI was created very recently, and it has not yet replicated across Entra ID.<br><br>Wait 30 to 60 seconds and rerun <code>terraform apply</code>.<br><br>Verify the subject exists with <code>az ad sp show --id &#x3C;UAMI_PRINCIPAL_ID></code>.</td></tr><tr><td><strong>Accidental UAMI deletion</strong><br><br><em>Error:</em> <code>terraform destroy deleted my customer-created UAMIs!</code></td><td>Destroy</td><td>The UAMIs were incorrectly placed inside the outpost's Cortex-managed resource group.<br><br>Terraform deletes UAMIs placed inside the outpost's Cortex-managed resource group during a destroy operation.<br><br>Recreate the UAMIs in a customer-owned resource group outside of the outpost boundaries and re-onboard.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cortex-docs.paloaltonetworks.com/cortex-xsiam/configure-cortex-xsiam/cortex-xsiam-data-sources/cloud-service-provider-csp-onboarding/outpost-onboarding/working-with-custom-outposts/custom-outpost-troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
