Troubleshoot BYOC

This topic introduces how to troubleshoot common issues with BYOC authorization, deployment, database operations, and connections. Start with the failed step and its exact error. Keep the original Terraform directory and state while diagnosing IAM setup. Do not delete existing roles or state merely to retry.

Local tools and IAM setup

Symptom	Action
terraform or aws: command not found	Install the required tools, reopen the terminal, and check terraform version and aws --version.
terraform init cannot download the provider	Check access to Terraform Registry and provider download services, including corporate proxy settings.
AWS authentication has expired	For SSO, run aws sso login --profile byoc-customer, then aws sts get-caller-identity --profile byoc-customer. Replace byoc-customer in both commands with your local AWS CLI profile name.
IAM AccessDenied	Ask your AWS administrator to check the local execution identity, AWS Organizations service control policies (SCPs), permissions boundaries, and permissions required by the template.
EntityAlreadyExists	Find the original directory/state for this data plane. Do not delete roles or state to bypass the conflict.
terraform apply fails partway through	Retain state, fix the error, then run terraform plan -out=tfplan in the same directory, review it, and apply the new plan.
terraform output has no outputs	Confirm you are in the original directory, state is present, and apply completed successfully.

AWS profile selects the wrong account

Check the profile name and Account in aws sts get-caller-identity. Environment credentials can override the chosen profile. If you intend to use the profile's credentials, remove these variables from the current terminal and check again:

unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
export AWS_PROFILE=byoc-customer
aws sts get-caller-identity

This clears only the current terminal variables; it does not delete the profile. Use your own profile name. Do not proceed until Account matches the intended customer account.

Role validation and data plane deployment

If the platform rejects the roles, verify both full ARNs, their account ID, the mapping to Deployment and Runtime fields, the trust-policy Principal, and the External ID. prefix_name and external_id must both equal the platform data plane ID. Newly created IAM roles can take time to propagate; retry validation after a short wait.

If the record remains Pending, return to Data Plane → Deploy and complete Credential Settings and Deployment Summary. Running the IAM template alone does not start deployment.

For Failed:

1. Open the data plane details and inspect the first failed stage in Deployment Timeline and the corresponding SYSTEM LOGS.
2. Record the error and check its cause with your AWS administrator: for example, denied role operations, account restrictions, or resource provisioning errors.
3. Correct the cause, then click Retry Deployment if available. Monitor the new attempt until Running or a new error appears.
4. If retry is unavailable or fails again, contact support with the data plane ID, region, failure time, and sanitized error details. Do not create a second record to work around the one-data-plane limit.

If progress updates are interrupted, use Reconnect progress. For a log-loading failure, use the log retry control; use Browse log history and Return to latest logs as needed. Check the data plane status to determine the deployment outcome before taking further action.

Database creation or capacity action unavailable

Check these items in order:

1. The selected organization is BYOC and you are its Organization Owner or the project's Project Admin.
2. The data plane is Running; for capacity changes, the database is also Running.
3. On License, status is Normal or Expiring and quota data has loaded. Retry loading errors before changing capacity.
4. Requested Query and Storage capacity each fit the remaining quota. For resize/scale, compare the increase over existing capacity, not the target's entire capacity.
5. All required fields are complete and options are supported for the tier. The selected Standard or Storage node specification must support the existing storage size.

If the license is Expired, use Contact Sales for renewal. If the quota is insufficient, reduce the selection or arrange more quota. See License and costs.

Connection failures

Symptom	Check
Timeout or DNS failure	Data plane/database state; public service or private endpoint readiness; application source IP; VPC/subnet, security group and DNS settings; correct endpoint host/port.
Authentication failure	Use a database username/password, not Cloud or AWS credentials. Check the user exists and use the password reset procedure if necessary.
Permission error after login	Check the database user's graph privileges for the attempted statement.

For private access, use the client VPC endpoint's DNS name from AWS. For public access, check the application's actual egress IP rather than relying only on Add Current IP Address. Follow Connect to a BYOC database.

Deletion blocked or resources remain

Delete all project databases before the data plane, and the data plane before the project. If a resource check fails, close the dialog and retry once the check is available. If a license error disables a database lifecycle action, restore license information or contact support.

Deleting a Failed or other non-Running data plane removes only its platform record. Work with support to identify and clean residual AWS resources. Retain both IAM roles until cleanup is verified. After infrastructure cleanup, use the IAM-template directory to remove the authorization; terraform destroy in this directory removes only the IAM resources created by the template.

When contacting support, provide organization/project/data plane identifiers, region, operation time, and the relevant error text. Remove AWS access keys, tokens, database passwords, and other secrets from logs and screenshots. Do not send Terraform state files by default.