Deployment: Invicti Platform on-demand, Invicti Platform on-premises
Package: Invicti API Security Standalone or Bundle
NTA troubleshooting
This document provides troubleshooting guidance for common issues when deploying and running Invicti Network Traffic Analyzer (NTA).
Authorization failures
If the NTA can't authorize with Invicti Platform (receiving HTTP 401 responses), it logs each failed heartbeat and keeps retrying every minute. It doesn't shut down, and its source shows Offline in the list of API sources. If the log shows ApiHubConfig decode error, the registration token is invalid, for example because it was truncated or modified.
Common causes of authorization failures:
- Invalid or expired registration token (registration tokens expire after 3 days on Invicti Platform on-demand and after 24 hours on Invicti Platform on-premises)
- The Reconstructor persistent volume was removed, so the stored usage token is lost
- Incorrect Invicti Platform credentials (email or license key)
- Network connectivity issues preventing access to Invicti Platform
- You skipped the Save step during token generation
To resolve:
-
Verify your registration token is valid and saved in Invicti Platform - go to Discovery >API configuration >API sources
-
Confirm your Invicti Platform email and license key are correct
-
Ensure network connectivity from your deployment environment to Invicti Platform
-
If the registration token expired or you removed the persistent volume, create a new NTA source and update your deployment configuration with its registration token
-
Review the NTA logs for specific error messages:
For Kubernetes deployments:
kubectl logs <reconstructor-pod-name> -n <your-namespace>For Docker deployments:
docker logs <container-name>
Token expiry after disconnection
After the NTA registers with its registration token, it authenticates with a usage token that it refreshes automatically. The usage token is valid for 90 days (2160 hours) and is stored on the Reconstructor persistent volume. If the NTA can't refresh the usage token before it expires, or the volume that stores it is removed, the token can no longer be used. When this happens, the NTA starts returning 401 Unauthorized heartbeat errors, keeps retrying every minute, and its source shows Offline in the list of API sources:
{"level":"error","message":"Heartbeat returned non-OK response","statusCode":401,"status":"401 Unauthorized"}
{"level":"warn","message":"Heartbeat failed; will retry on next tick","statusCode":401}
This is expected behavior. Common triggers include leaving the NTA stopped until the usage token expires, removing the persistent volume (for example, with docker compose down --volumes or by deleting the PersistentVolume), letting the registration token expire before the NTA first connects, and reusing the source with a new registration token after removing the volume. A new token on the existing source connects the NTA only until that token expires.
To restore the connection (Kubernetes): Create a new NTA source and generate its registration token as described in Generate a new registration token. Then run the install command for your integration with the new token and the reconstructor.persistentVolume.nodeName parameter. For details, see Reuse NTA importer.
To restore the connection (Docker Compose):
-
Create a new NTA source and generate its registration token in Invicti Platform. For instructions, see Generate a new registration token.
-
Open
docker-compose.ymland replace the value ofAPIHUB_CONFIGwith the new token:environment:
APIHUB_CONFIG: YOUR_NEW_REGISTRATION_TOKEN_HERE -
Force-recreate the reconstructor container to apply the change:
docker compose -f docker-compose.yml up -d --force-recreate reconstructor -
Confirm the connection is restored:
docker compose logs -f reconstructorLook for
Heartbeat completed successfullyin the output.
Pod/container status issues
If NTA components are in CrashLoopBackOff or Error states, review the logs for specific error messages and verify:
- The registration token is valid and properly configured
- Network policies allow outbound connections to Invicti Platform
- Resource limits are appropriate for your traffic volume
- You've set all required environment variables correctly
Review pod status (Kubernetes):
kubectl get pods -n <your-namespace>
Review container status (Docker):
docker ps -a
Network connectivity issues
If the NTA can't reach Invicti Platform:
-
Verify firewall rules allow outbound HTTPS connections
-
Review proxy configurations if using a corporate proxy
-
Ensure Domain Name System (DNS) resolution works for Invicti Platform endpoints
-
Test connectivity from your deployment environment:
curl -I https://platform.invicti.com
No APIs appearing in API Inventory
If the NTA is running but APIs aren't appearing in your API Inventory:
- Verify traffic is actually flowing through the monitored interfaces/endpoints
- Verify that traffic matches the capture criteria (HTTP methods, status codes)
- Confirm the NTA has successfully authorized (review logs)
- Wait a few minutes - API reconstruction and sync may take time
- Review the reconstructor logs for processing errors
Need help?
Invicti Support team is ready to provide you with technical help. Go to Help Center