From 12e523290a6cf7b43903876ed884d2a64c3ea071 Mon Sep 17 00:00:00 2001 From: way zheng Date: Fri, 14 Nov 2025 15:25:06 -0800 Subject: [PATCH 1/2] add code E12 = download erros --- docs/guides/operator-guide-aws-marketplace.md | 8 ++++++++ docs/guides/operator-guide-azure-enclave.md | 10 +++++++++- docs/guides/operator-private-gcp-confidential-space.md | 8 ++++++++ 3 files changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/guides/operator-guide-aws-marketplace.md b/docs/guides/operator-guide-aws-marketplace.md index 21f39b0a9..4f019a366 100644 --- a/docs/guides/operator-guide-aws-marketplace.md +++ b/docs/guides/operator-guide-aws-marketplace.md @@ -376,6 +376,14 @@ Error codes for Private Operator startup issues are applicable only to release v | E05 | OperatorKeyValidationError | Ensure the operator key is correct for the environment and matches the one provided to you. | | E06 | UID2ServicesUnreachableError | Allow UID2 core and opt-out service IP addresses in the egress firewall. For IP addresses and DNS details, refer to the logs. | +### Runtime Errors + +The following errors occur during operator runtime (after startup): + +| Error Code | Issue | How to Identify in Logs | Steps to Resolve | +| :--- | :--- | :--- | :--- | +| E12 | Data Download Failure | Look for log messages containing `"Cannot download required files"` along with `"Failed to load"` errors from `RotatingStoreVerticle`. These will include HTTP status codes (e.g., `"HTTP response code 403"`) or exception types (e.g., `"exception: RequestTimeoutException"`). | Check the HTTP status code or exception in the error message:
**404 errors** - Verify operator key is valid and configuration paths are correct.
**403 errors** - Check IAM permissions for S3 access and verify operator credentials.
**Timeout errors** - Verify network connectivity, check firewall/security group settings allow outbound HTTPS, and ensure UID2 service endpoints are accessible.
**500 errors** - Temporary UID2 service issue, retry or contact UID2 support if persistent. | + ## Technical Support If you have trouble subscribing to the product, or deploying, [contact us](mailto:aws-mktpl-uid@thetradedesk.com). diff --git a/docs/guides/operator-guide-azure-enclave.md b/docs/guides/operator-guide-azure-enclave.md index 9d65c0714..5f49c07b9 100644 --- a/docs/guides/operator-guide-azure-enclave.md +++ b/docs/guides/operator-guide-azure-enclave.md @@ -350,4 +350,12 @@ Error codes for Private Operator startup issues are applicable only to release v | E04 | ConfigurationValueError | A configuration value is invalid. Verify that the configuration values align with the required format and environment. Note: `debug_mode = true` is allowed only in the `integ` environment. Check the logs for more details. | | E05 | OperatorKeyValidationError | Ensure the operator key is correct for the environment and matches the one provided to you. | | E06 | UID2ServicesUnreachableError | Allow UID2 core and opt-out service IP addresses in the egress firewall. For IP addresses and DNS details, refer to the logs. | -| E08 | OperatorKeyPermissionError | The managed identity (specified via the `operatorIdentifier` parameter) that launches the container must have access to the key vault where the operator key is stored. The value of `operatorIdentifier` must be identical across all configuration JSON files. | \ No newline at end of file +| E08 | OperatorKeyPermissionError | The managed identity (specified via the `operatorIdentifier` parameter) that launches the container must have access to the key vault where the operator key is stored. The value of `operatorIdentifier` must be identical across all configuration JSON files. | + +### Runtime Errors + +The following errors occur during operator runtime (after startup): + +| Error Code | Issue | How to Identify in Logs | Steps to Resolve | +| :--- | :--- | :--- | :--- | +| E12 | Data Download Failure | Look for log messages containing `"Cannot download required files"` along with `"Failed to load"` errors from `RotatingStoreVerticle`. These will include HTTP status codes (e.g., `"HTTP response code 403"`) or exception types (e.g., `"exception: RequestTimeoutException"`). | Check the HTTP status code or exception in the error message:
**404 errors** - Verify operator key is valid and configuration paths are correct.
**403 errors** - Check managed identity permissions for storage access and verify operator credentials.
**Timeout errors** - Verify network connectivity, check NSG/firewall rules allow outbound HTTPS, and ensure UID2 service endpoints are accessible.
**500 errors** - Temporary UID2 service issue, retry or contact UID2 support if persistent. | \ No newline at end of file diff --git a/docs/guides/operator-private-gcp-confidential-space.md b/docs/guides/operator-private-gcp-confidential-space.md index d7bca3517..41f1f0e4f 100644 --- a/docs/guides/operator-private-gcp-confidential-space.md +++ b/docs/guides/operator-private-gcp-confidential-space.md @@ -546,3 +546,11 @@ Error codes for Private Operator startup issues are applicable only to release v | E05 | OperatorKeyValidationError | Ensure the operator key is correct for the environment and matches the one provided to you. | | E06 | UID2ServicesUnreachableError | Allow UID2 core and opt-out service IP addresses in the egress firewall. For IP addresses and DNS details, refer to the logs. | | E08 | OperatorKeyPermissionError | Attach a service account to the Compute Engine instance template. The UID2 Operator needs these permissions to access the operator key from the GCP Secret Manager. | + +### Runtime Errors + +The following errors occur during operator runtime (after startup): + +| Error Code | Issue | How to Identify in Logs | Steps to Resolve | +| :--- | :--- | :--- | :--- | +| E12 | Data Download Failure | Look for log messages containing `"Cannot download required files"` along with `"Failed to load"` errors from `RotatingStoreVerticle`. These will include HTTP status codes (e.g., `"HTTP response code 403"`) or exception types (e.g., `"exception: RequestTimeoutException"`). | Check the HTTP status code or exception in the error message:
**404 errors** - Verify operator key is valid and configuration paths are correct.
**403 errors** - Check service account permissions for storage access and verify operator credentials.
**Timeout errors** - Verify network connectivity, check VPC firewall rules allow outbound HTTPS, and ensure UID2 service endpoints are accessible.
**500 errors** - Temporary UID2 service issue, retry or contact UID2 support if persistent. | From f01e2261765a415a71cecc90e486c8c880cffb0e Mon Sep 17 00:00:00 2001 From: way zheng Date: Mon, 17 Nov 2025 00:22:58 -0800 Subject: [PATCH 2/2] be consistent with the existing table --- docs/guides/operator-guide-aws-marketplace.md | 12 +++++++----- docs/guides/operator-guide-azure-enclave.md | 10 +--------- .../operator-private-gcp-confidential-space.md | 8 -------- 3 files changed, 8 insertions(+), 22 deletions(-) diff --git a/docs/guides/operator-guide-aws-marketplace.md b/docs/guides/operator-guide-aws-marketplace.md index 4f019a366..03ebc9128 100644 --- a/docs/guides/operator-guide-aws-marketplace.md +++ b/docs/guides/operator-guide-aws-marketplace.md @@ -361,12 +361,16 @@ The following table includes some additional commands that might help you manage ## UID2 Operator Error Codes -The following table lists errors that might occur during a Private Operator's startup sequence. +The following sections list error codes that might occur during a Private Operator's startup or runtime. :::note -Error codes for Private Operator startup issues are applicable only to release v5.49.7 and later. +Error codes for Private Operator issues are applicable only to release v5.49.7 and later. ::: +### Startup Errors + +The following errors occur during operator startup: + | Error Code | Issue | Steps to Resolve | | :--- | :--- | :--- | | E01 | InstanceProfileMissingError | Attach an IAM instance profile to the EC2 instance with the required permissions. The UID2 Operator needs these permissions to access configurations from AWS Secrets Manager. | @@ -376,13 +380,11 @@ Error codes for Private Operator startup issues are applicable only to release v | E05 | OperatorKeyValidationError | Ensure the operator key is correct for the environment and matches the one provided to you. | | E06 | UID2ServicesUnreachableError | Allow UID2 core and opt-out service IP addresses in the egress firewall. For IP addresses and DNS details, refer to the logs. | -### Runtime Errors - The following errors occur during operator runtime (after startup): | Error Code | Issue | How to Identify in Logs | Steps to Resolve | | :--- | :--- | :--- | :--- | -| E12 | Data Download Failure | Look for log messages containing `"Cannot download required files"` along with `"Failed to load"` errors from `RotatingStoreVerticle`. These will include HTTP status codes (e.g., `"HTTP response code 403"`) or exception types (e.g., `"exception: RequestTimeoutException"`). | Check the HTTP status code or exception in the error message:
**404 errors** - Verify operator key is valid and configuration paths are correct.
**403 errors** - Check IAM permissions for S3 access and verify operator credentials.
**Timeout errors** - Verify network connectivity, check firewall/security group settings allow outbound HTTPS, and ensure UID2 service endpoints are accessible.
**500 errors** - Temporary UID2 service issue, retry or contact UID2 support if persistent. | +| E12 | Data Download Failure | Look for log messages containing `"E12: Data Download Failure"` along with `"Failed to load"` errors from `RotatingStoreVerticle`. These will include HTTP status codes (e.g., `"HTTP response code 403"`) or exception types (e.g., `"exception: IOException"`). | Check the HTTP status code or exception in the error message:
**404 errors** - Verify operator key is valid and configuration paths are correct.
**403 errors** - Check IAM permissions for S3 access and verify operator credentials.
**Timeout errors** - Verify network connectivity, check firewall/security group settings allow outbound HTTPS, and ensure UID2 service endpoints are accessible.
**500 errors** - Temporary UID2 service issue, retry or contact UID2 support if persistent. | ## Technical Support diff --git a/docs/guides/operator-guide-azure-enclave.md b/docs/guides/operator-guide-azure-enclave.md index 5f49c07b9..9d65c0714 100644 --- a/docs/guides/operator-guide-azure-enclave.md +++ b/docs/guides/operator-guide-azure-enclave.md @@ -350,12 +350,4 @@ Error codes for Private Operator startup issues are applicable only to release v | E04 | ConfigurationValueError | A configuration value is invalid. Verify that the configuration values align with the required format and environment. Note: `debug_mode = true` is allowed only in the `integ` environment. Check the logs for more details. | | E05 | OperatorKeyValidationError | Ensure the operator key is correct for the environment and matches the one provided to you. | | E06 | UID2ServicesUnreachableError | Allow UID2 core and opt-out service IP addresses in the egress firewall. For IP addresses and DNS details, refer to the logs. | -| E08 | OperatorKeyPermissionError | The managed identity (specified via the `operatorIdentifier` parameter) that launches the container must have access to the key vault where the operator key is stored. The value of `operatorIdentifier` must be identical across all configuration JSON files. | - -### Runtime Errors - -The following errors occur during operator runtime (after startup): - -| Error Code | Issue | How to Identify in Logs | Steps to Resolve | -| :--- | :--- | :--- | :--- | -| E12 | Data Download Failure | Look for log messages containing `"Cannot download required files"` along with `"Failed to load"` errors from `RotatingStoreVerticle`. These will include HTTP status codes (e.g., `"HTTP response code 403"`) or exception types (e.g., `"exception: RequestTimeoutException"`). | Check the HTTP status code or exception in the error message:
**404 errors** - Verify operator key is valid and configuration paths are correct.
**403 errors** - Check managed identity permissions for storage access and verify operator credentials.
**Timeout errors** - Verify network connectivity, check NSG/firewall rules allow outbound HTTPS, and ensure UID2 service endpoints are accessible.
**500 errors** - Temporary UID2 service issue, retry or contact UID2 support if persistent. | \ No newline at end of file +| E08 | OperatorKeyPermissionError | The managed identity (specified via the `operatorIdentifier` parameter) that launches the container must have access to the key vault where the operator key is stored. The value of `operatorIdentifier` must be identical across all configuration JSON files. | \ No newline at end of file diff --git a/docs/guides/operator-private-gcp-confidential-space.md b/docs/guides/operator-private-gcp-confidential-space.md index 41f1f0e4f..d7bca3517 100644 --- a/docs/guides/operator-private-gcp-confidential-space.md +++ b/docs/guides/operator-private-gcp-confidential-space.md @@ -546,11 +546,3 @@ Error codes for Private Operator startup issues are applicable only to release v | E05 | OperatorKeyValidationError | Ensure the operator key is correct for the environment and matches the one provided to you. | | E06 | UID2ServicesUnreachableError | Allow UID2 core and opt-out service IP addresses in the egress firewall. For IP addresses and DNS details, refer to the logs. | | E08 | OperatorKeyPermissionError | Attach a service account to the Compute Engine instance template. The UID2 Operator needs these permissions to access the operator key from the GCP Secret Manager. | - -### Runtime Errors - -The following errors occur during operator runtime (after startup): - -| Error Code | Issue | How to Identify in Logs | Steps to Resolve | -| :--- | :--- | :--- | :--- | -| E12 | Data Download Failure | Look for log messages containing `"Cannot download required files"` along with `"Failed to load"` errors from `RotatingStoreVerticle`. These will include HTTP status codes (e.g., `"HTTP response code 403"`) or exception types (e.g., `"exception: RequestTimeoutException"`). | Check the HTTP status code or exception in the error message:
**404 errors** - Verify operator key is valid and configuration paths are correct.
**403 errors** - Check service account permissions for storage access and verify operator credentials.
**Timeout errors** - Verify network connectivity, check VPC firewall rules allow outbound HTTPS, and ensure UID2 service endpoints are accessible.
**500 errors** - Temporary UID2 service issue, retry or contact UID2 support if persistent. |