FAQ & Troubleshooting

Frequently asked questions

We don't use AWS VPC IPAM. Can the integration discover IP information through other AWS endpoints?

Not currently. To use the integration you must have AWS VPC IPAM enabled. Support for other AWS endpoints may be added in the future.

Is the integration free to use?

The AWS VPC IPAM integration is available with commercial editions of NetBox (NetBox Cloud and NetBox Enterprise).

Do I need NetBox Assurance?

Yes. The integration extracts and transforms the latest state from AWS VPC IPAM and sends it to NetBox Assurance, where you control how it is ingested into NetBox.

Where do my AWS credentials go?

Into the policy config block, as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Reference them with ${...} substitution so the agent replaces them with environment variables from its own process when it loads the policy, rather than storing the secret in the file. You run the agent and you hold the credentials; NetBox Labs never holds them, and nothing about them is stored in NetBox.

Do I need to configure an External ID?

No. AWS_ROLE_ARN assumes a role you own, in another AWS account you own, so both sides of the trust relationship are yours. NetBox Labs never assumes a role in your account, which is the case an External ID exists to protect.

Can I use a named AWS CLI profile?

The AWS_PROFILE policy config key was removed and is no longer read. Supply credentials in the policy config block, or run the agent inside AWS with an attached instance or task role. With both credential keys unset, the standard boto3 credential chain still applies, so anything that chain resolves in the agent's own environment is what gets used.

Does the integration create NetBox Roles?

No. A prefix built from a VPC resource CIDR is set to NetBox's built-in container status, because a VPC CIDR is the aggregate that holds its subnets. Nothing is assigned a Role, so the integration cannot collide with prefix roles you curate yourself.

Which NetBox versions are supported?

NetBox 4.1 and above.

Which AWS VPC IPAM versions are supported?

The integration is maintained to remain compatible with the latest AWS APIs available in the boto3 library. The Advanced Tier is required for private IP management.

Can the integration push scopes and pools from NetBox back to AWS VPC IPAM?

No. Data flows one way only, from AWS VPC IPAM into NetBox.

Does the integration create NetBox Tenants?

No. Region grouping is expressed through the aws:<region> tag applied to every object, so the integration does not impose a tenant structure on your NetBox data.

Does the integration delete objects from NetBox?

No, it never deletes. Applying its deviations creates objects that do not yet exist and updates ones whose AWS data has changed. An object that no longer exists in AWS is left untouched in NetBox rather than removed. Object lifecycle management, including deletes, is coming soon.

Why don't my public IPAM scopes appear in NetBox?

The AWS_VPC_IPAM_SCOPE_TYPE config key defaults to private, so only private scopes are ingested. Set it to public or all to include public scopes.

Common issues

Missing or incomplete AWS credentials:
```
AWS credentials not found or incomplete. Please configure your AWS credentials
(e.g., via environment variables, ~/.aws/credentials, or an assumed role).
```
Solution: Confirm that credentials reach the integration through one of the supported methods: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the policy config block, an instance or task role attached to an agent running inside AWS, or AWS_ROLE_ARN layered on top of either. Credential errors abort the whole run.
AWS rejected the credentials supplied in the policy config:
```
AWS rejected the credentials supplied in policy config
(AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY): ... This applies to every region,
not just this one — verify the access key is correct, active, and not expired.
```
or, when AWS_ROLE_ARN is set:
```
AWS rejected the assumed-role session credentials for arn:aws:iam::...:role/... : ...
This applies to every region, not just this one — verify the role still exists, its
trust policy still permits this identity, and its session hasn't been revoked.
```
Solution: Check that the access key is active and not deleted in IAM, or that the assumed role still exists with a trust policy that permits your identity. A common cause is a ${...} reference whose environment variable was never set: the literal text is passed through as the credential and AWS rejects it. This aborts the run rather than being retried per region, because the same rejection would repeat in every region.
Only one of the two access-key config keys is set:
```
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY must both be set together, or both
omitted to fall back to the default credential chain (an in-AWS instance role).
```
Solution: Set both keys, or remove both to use an attached instance or task role. A common cause is one of the two ${...} references resolving and the other not.
AWS_SESSION_TOKEN set without the access keys:
```
AWS_SESSION_TOKEN requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to also be
set (temporary credentials are issued as a triplet).
```
Solution: Supply all three values, or remove the session token. Temporary credentials expire, so prefer a durable IAM user key or AWS_ROLE_ARN for a scheduled sync.
A credential key is set but empty:
```
AWS_SECRET_ACCESS_KEY is set but empty. Leave it unset to fall back to the default
credential chain, or provide a non-empty value (check the ${...} env/Vault
substitution source).
```
Solution: The value is present but blank, most often an environment variable exported with an empty value, or a key left blank in the policy file. Give it a real value or remove the key entirely. The run fails rather than falling back, so it cannot silently read IPAM as an unintended identity.

An environment variable that is not set at all behaves differently: the ${...} reference is left in place as literal text and passed to AWS as the credential, which produces the rejection in issue 2 rather than this error.
Missing region:
```
AWS_VPC_IPAM_REGION must be provided in policy config
```
or
```
AWS_VPC_IPAM_REGION must contain at least one non-empty region
```
Solution: Set AWS_VPC_IPAM_REGION in the policy config block to a single region, a comma-separated list, or a YAML list of regions.
Invalid scope type:
```
AWS_VPC_IPAM_SCOPE_TYPE must be one of ('private', 'public', 'all'), got ...
```
Solution: Set AWS_VPC_IPAM_SCOPE_TYPE to private, public, or all, or remove it to use the private default.
Cross-account role assumption fails:
```
Failed to assume role arn:aws:iam::...:role/... : ...
```
Solution: Verify the AWS_ROLE_ARN value, that the source identity is permitted to call sts:AssumeRole on the target role, and that the target role's trust policy allows the source identity. AssumeRole failures abort the whole run.
No IPAMs found in a region:
```
No IPAMs found in region <region>
```
Solution: Confirm that AWS VPC IPAM is enabled in the specified region and that the IAM identity has the required ec2:DescribeIpams permission. This is logged as a warning and that region produces no entities.
A configured scope ID matched nothing:
```
AWS_VPC_IPAM_SCOPE_IDS lists scope ID(s) not found in any processed region: ...
```
Solution: Check the scope IDs in AWS_VPC_IPAM_SCOPE_IDS for typos, whether they belong to a region not listed in AWS_VPC_IPAM_REGION, or whether their region failed to process (see earlier per-region errors in the log).
Permission errors accessing the mounted directory:

The agent cannot read the config file or write dry-run output, and fails with a permission error naming the mounted path (for example /opt/orb/). The exact wording comes from the operating system, not from the integration.

Solution: Ensure the directory you mount with -v is readable, and writable if you use dry-run mode, by the agent container.

Support

Email support@netboxlabs.com for support.

Frequently asked questions

Common issues

Support

On this page