Support
Troubleshooting guides
Answer each check with yes or no. A “no” shows the fix; if every check passes you get the details to include when you contact support.
The agent will not connect or enroll
A new agent never appears in the console, or enrollment fails.
Check 1 of 5: Is the agent container or pod running?
docker ps, docker compose ps, or kubectl get pods in the agent namespace.
Show every check for this guide
- Is the agent container or pod running? If not: Start it and read its JSON logs on stderr. A configuration problem stops it at start-up with AGENT_CONFIG_INVALID; run `datanivra-agent check` to see which setting is rejected.
- Does `datanivra-agent check` pass and print the control-plane URL you expect? If not: Set DATANIVRA_AGENT_CONTROL_PLANE_URL to your control-plane https:// address. Plain http is refused outside local demos.
- Can the agent host reach the control plane with outbound HTTPS on port 443? If not: Allow outbound 443 to the control-plane address in your firewall. The agent honours HTTPS_PROXY; for a TLS-inspecting proxy set DATANIVRA_AGENT_CA_BUNDLE to the proxy’s CA file. No inbound port is ever needed.
- Is a fresh, unused enrollment token configured? If not: Create a new enrollment token in the console and supply it through the secret reference, then restart the agent. Never paste tokens into tickets or chat.
- Does the agent have its own state directory (not shared with another agent)? If not: Give each agent its own persistent state volume. Two agents with one key are refused (PUBLIC_KEY_IN_USE).
The agent shows OFFLINE or its heartbeat is missing
The console marks an agent OFFLINE and jobs stay QUEUED.
Check 1 of 4: Is the agent process still running?
An agent is shown OFFLINE when no heartbeat arrived for the configured window (180 seconds by default).
Show every check for this guide
- Is the agent process still running? If not: Restart it. Queued work simply waits; nothing runs until the agent leases it again.
- Are its logs free of CONTROL_PLANE_UNAVAILABLE and HTTP 5xx retries? If not: Check outbound 443, proxy and CA bundle as for a new agent. Reports wait in the local outbox and are delivered in order once the connection returns.
- Is the agent host clock synchronised (NTP)? If not: Fix time synchronisation on the host, then restart the agent.
- Is the agent still active (not revoked) in the console? If not: A revoked agent stops all work and publishes nothing. Enroll a replacement with a new token if the revocation was intended.
A source connection fails
Validating or discovering a source ends with a connector or secret error.
Check 1 of 5: Is the connector kind available today?
The integrations page lists every connector as Available now, Preview or Planned.
Show every check for this guide
- Is the connector kind available today? If not: Planned kinds fail with CONNECTOR_NOT_AVAILABLE. Use a shipped connector, for example export to Parquet and read it with the Local files, S3 or Azure connector.
- Does the connection secret resolve on the agent host? If not: Fix the reference or the secret. The code tells you which: not found, not JSON, field missing, file permissions or scheme not configured.
- Is the connection document valid? If not: Unknown fields and plain-text credentials are rejected. Give credentials as <field>_ref secret references.
- Can the agent host reach the source (network route, DNS, TLS)? If not: Open the route from the agent to the source and provide the CA. Error messages carry codes only; host names and users are never reported.
- Is the credential proven (or attested) read-only? If not: Remove write privileges. For object stores and non-PostgreSQL SQL dialects, which cannot be introspected, apply least-privilege grants and set read_only_attested.
Discovery finished but found no tables
A discovery job succeeded yet the catalog is empty or missing tables.
Check 1 of 3: Does the schema filter include the schemas you expect?
The optional `schemas` list in the connection document limits discovery.
Show every check for this guide
- Does the schema filter include the schemas you expect? If not: Add the schemas (plain identifiers) or remove the filter, then run discovery again.
- Can the source credential see the tables? If not: Grant USAGE on the schema and SELECT on the tables to the read-only role.
- For file sets: do the files match the configured format and table mapping? If not: Fix `format`, declare `tables` (logical name → path) and, for CSV, declare has_header.
Certification failed
A dataset version ended FAILED at the certification step.
Check 1 of 3: Have you opened the version’s evidence to see which gate failed?
The console shows each certification gate outcome; the evidence files stay inside your environment.
Show every check for this guide
- Have you opened the version’s evidence to see which gate failed? If not: Open the dataset version’s evidence first: the failed gate tells you what to fix.
- Does the masking policy cover every column classified as sensitive? If not: Add a rule for the uncovered column, get the new policy version approved, and request a new dataset version. This refusal is the product working as designed.
- Are all relationships intact (no dangling references)? If not: Add the missing relationship or parent table to the subset definition and rebuild.
Provisioning failed
A certified dataset could not be delivered to a target environment.
Check 1 of 4: Is the version certified and not revoked?
Show every check for this guide
- Is the version certified and not revoked? If not: Only certified versions provision. Request a new version.
- Is the target served by the agent that built the version? If not: Provision from that agent or rebuild the version on the target’s agent.
- Is the target environment reachable and not expired? If not: Restore connectivity from the agent to the target or extend the environment.
- Does the target credential have write access, and are the target tables free? If not: Grant write access to the target schema. DataNivra will not overwrite tables it does not manage.
Billing and plan issues
An action is blocked by your plan, your trial ended, or a payment did not go through.
Check 1 of 3: Is your trial or subscription active?
Billing & Plan in the console shows your plan and its state.
Show every check for this guide
- Is your trial or subscription active? If not: After a trial ends the organisation becomes read-only: nothing is deleted immediately and you can upgrade from Billing & Plan at any time.
- Are you within your plan’s limits (agents, sources, jobs, datasets)? If not: Upgrade in Billing & Plan, or free capacity, for example by revoking an unused agent.
- Did your last payment succeed? If not: Update the payment method on the payment provider’s hosted page linked from Billing & Plan. DataNivra never sees your card number.
Back to the support center · Browse the error codes
Still stuck? Contact support
Include the error code, the job, dataset or agent id and the time it happened. Never send credentials, enrollment tokens, secret values or source data — support never needs them.