The scanner does not register
The deployment stays Not registered after apply.Start the coordinator now
Run the command in the module’s
run_now_command output (on-prem: sudo systemctl start tigergate-dspm.service)
so you do not wait for the next 15-minute tick.Read the logs
See Get the logs. The scanner names the problem and the variables involved.
Check the way out
The scanner needs outbound HTTPS to the
tigergate_api_url of your organization’s region. Without a NAT gateway,
proxy or route, it starts but cannot reach TigerGate.Refusals of the organization API key
| Shown as | Cause | Fix |
|---|---|---|
| No organization API key | The scanner sent no key. | Set tigergate_api_key, or the platform’s secret input, and apply again. On-prem, write api-key.env. |
| Organization API key not recognised | The key was mistyped or deleted. | Put a valid key in the secret, or apply a new one with tigergate_api_key_version raised by one. |
| Organization API key revoked, or expired | The key was revoked or is past its expiry. | Create a new key and replace it the same way. |
| API key from another organization | The key belongs to a different TigerGate organization. | Use a key from the organization that owns the deployment. |
| Organization inactive or suspended | The subscription is inactive. | Contact your account owner or billing. The scanner resumes at its next check. |
| DSPM not enabled | DSPM is not on the subscription. | Ask your account owner to enable it. |
Refusals of the enrollment token
| Code | Cause | Fix |
|---|---|---|
unauthorized | The token is wrong or was revoked. | Select Re-register on the deployment and use the new token. |
enrollment_consumed | The token was already used to register, possibly by another account or a rebuilt deployment. | Select Re-register and use the new token. Each account needs its own deployment. |
account_mismatch | The scanner runs in a different account, subscription or project from the deployment’s. | Use the token of the deployment for that account, or add a deployment for it. |
platform_mismatch | The module’s platform differs from the deployment’s. | Use the module for the deployment’s platform. |
deployment_revoked | The deployment was revoked. | Create a new deployment. |
The scanner credential is rejected
After it registers, the scanner uses its own credential. If TigerGate stops accepting it, for example because another registration of the same deployment replaced it, the scanner stops with exit code3 and a log line that says the
credential was refused. To recover:
Create a new enrollment token
Select Re-register on the deployment’s Overview tab. Copy the token: it is shown once.
Put it in place
Write it to the enrollment token secret, or set it as
enrollment_token in your tfvars with
enrollment_token_version raised by one, and run terraform apply. On-prem, write it to enrollment.env.Let the next run register
At its next run the coordinator finds its credential refused, sees a token it has not used, and registers again.
TigerGate replaces the credential and keeps the deployment’s fingerprint key, so earlier fingerprints still match. To
skip the wait, start the coordinator with the
run_now_command output.3 and says that
no new enrollment token is configured. A refusal that was not about the token itself, such as a network error, is
tried again at the next run. A revoked deployment cannot register again; create a new one.
If the scanner still does not register, or you want to replace a credential that still works, clear the stored
credential after you put the new token in place: write {} to the scanner credential secret (AWS: the
scanner_credential_secret_arn output; Azure: the Key Vault secret scanner-credential; Google Cloud:
<prefix>-scanner-credential), or delete credential.json from the on-prem state directory. Then start the
coordinator.
Deployment status
| Status | What to check |
|---|---|
| Failing | The reason names a failed preflight check, a failed run, or a refusal. Open Preflight or Errors for the fix. |
| Degraded | The last run had store errors, or a preflight check warned. Scanning works, with gaps. |
| Stale | No call for 45 minutes. The trigger may be disabled (schedule_enabled = false on AWS), the task may fail to start (image pull, subnets without egress, a quota), or the on-prem host or timer may be down. |
Preflight checks
The scanner runs preflight checks on every run and posts them to the deployment. Each failed check has its fix. On AWS the checks include:| Check | What it tests |
|---|---|
identity.sts | Who the scanner runs as. |
egress.ingest | The way out to the TigerGate API. |
queue.access, state.access | The work queue and the state table the module created. |
regions.enabled | Regions that are opted out or denied by an SCP. |
kms.decrypt | Decryption through the data services. |
s3.inventory | Whether S3 Inventory can replace listing. |
perm.<service>.<probe> | Each read the scan policy grants, for example perm.s3.read or perm.rds.describe. |
db.<identifier>, fileshare.<id> | Each database and file share it will read. |
target.<id>, and the result shows beside the target on the Configuration tab. A missing
grant affects only that feature’s stores.
Store and run errors
Each unreadable store is listed on the Errors tab with one of these classes. A store in any of them is never shown as clean.| Class | Meaning and fix |
|---|---|
Access denied (access_denied) | The scanner identity was refused. Check that the scan policy is attached and that no SCP, permission boundary, bucket policy or firewall denies it. |
Key access denied (kms_denied) | A customer managed key the scanner cannot use. Allow the scanner role in the key policy, or list the key in kms_key_arns. |
Network unreachable (network_unreachable) | No route to the host. Check NAT or endpoints, security groups and network ACLs. Private databases must allow the scanner’s security group. |
Name not resolved (dns_failure) | Check VPC DNS settings, private hosted zones and forwarding rules. |
TLS error (tls_error) | Check the endpoint certificate and any proxy that intercepts TLS. |
Throttled (throttled) | The provider throttled the scanner. It retries; lower Max workers or Shards per worker if this keeps happening. |
Timed out (timeout) | Raise Max workers, or exclude large paths you do not need classified. |
Not found (not_found) | The resource was deleted or moved during the run. |
Unsupported format (unsupported_format) | Objects no reader classifies, such as SQLite files and images. They stay in inventory without classification. |
Too large (too_large) | An object over the 512 MiB in-memory bound for its format. |
Quota exceeded (quota_exceeded) | A service quota in your account, such as concurrent tasks or vCPUs. Raise it, or lower Max workers. |
Credential rejected (credential_expired) | TigerGate rejected the scanner credential. Create a new token with Re-register, put it in place and apply; the scanner registers again on its next run. See the scanner credential is rejected. |
Organization API key or organization refused (api_key_missing, api_key_invalid, api_key_revoked, api_key_expired, api_key_org_mismatch, org_blocked, product_not_entitled) | Replace the API key, or restore the subscription. See Refusals of the organization API key. |
Configuration refused (config_invalid) | The message names the field or reason. Fix it on the Configuration tab. |
Work queue failed, State store failed (queue_error, state_store_error) | Check that the queue and state store the module created still exist and that the scanner can use them. |
Gave up after retries (dead_letter) | Shards failed every attempt. Fix the store’s last error and run again. |
Superseded (superseded) | A new run started before this one ended. Nothing to do unless it repeats. |
Stopped reporting (abandoned) | No progress for 6 hours. Check the logs and that the tasks still run. |
Scanner error (internal) | If it repeats, send the run id to support. |
Coverage gaps
Deployments → Coverage counts stores discovered, read, refused and not scanned yet. Under What is missing, and why, each gap has a cause, such as Access denied, Not scanned yet, No reader for this store type, Not reachable from here or Partially read, and a fix.SaaS and warehouse connections
| What you see | Fix |
|---|---|
| Content access failed | The connection’s credential cannot read content. Add the missing permission (the reason names it), then select Verify now. |
| Nothing is read | What to read is empty: tick Scan every data store or add an include. |
| Throttled | The provider rate-limited the connection. It resumes when the pause ends; lower Jobs in flight if it repeats. |
| Slack messages not read | Add the channels:history and groups:history scopes and invite the bot to the channels. |
| Box reads only some files | Enable the as-user header and Manage users on the Box app. |
| A warehouse table is not read | The warehouse must be reachable over a public address. Databricks needs a SQL warehouse ID to read rows. |
auth, denied, throttled, quota, not_found, unreachable, provider_error
or unsupported) and a remediation. After fixing access on the provider’s side, select Rescan now on the store
or the connection.
Get the logs
- AWS
- Azure
- Google Cloud
- On-prem
tigergate-dspm with your name_prefix if you changed it.log_level = "debug" in the
module for more detail. Its exit code says what stopped it: 0 done or no run due, 1 configuration error, 2
blocked by TigerGate (billing or a revoked deployment), 3 credential or API key rejected, 4 fatal runtime error.