DFS Lite Troubleshooting

Use this page when connector data is missing, stale, incorrectly mapped, or failing quality checks.

Triage order

Start with the smallest possible check:

1. Confirm the user has access.
2. Confirm connector status.
3. Test the connector.
4. Browse source.
5. Preview source values.
6. Check mappings.
7. Run sync.
8. Check sync history.
9. Check data quality.
10. Review rejected rows when available.

Access problems

Symptom	Likely cause	Action
Data Integration is hidden	Tenant access or navigation permission missing.	Ask administrator to confirm access.
Connectors are visible but actions are blocked	Missing dfs:write.	Request write access for connector operation.
Delete action is blocked	Missing dfs:delete.	Ask a data administrator to handle deletion.
DFS Pro pages are unavailable	dfs-pro package gate is not enabled.	Confirm tenant package enablement.

Connector test fails

Check:

• credentials;
• host, port, URL, topic, or table name;
• protocol security settings;
• VPN, firewall, or allowlist;
• source-side read permissions;
• certificate or token expiration;
• source service availability.

If test fails after a previously working connection, ask whether the source system changed credentials, endpoint, certificate, schema, or network route.

Browse works but preview fails

Likely causes:

• selected node has no recent value;
• source path is a folder or object instead of a value;
• payload field path is wrong;
• query returns metadata instead of records;
• connector needs an active session;
• source permissions allow browse but block read.

Actions:

1. Select a narrower source path.
2. Preview a known-good field.
3. Ask source owner for a reference value.
4. Check connector logs.
5. Re-test connection.

Data arrives but mapping is wrong

Likely causes:

• source path points to the wrong field;
• target ID points to the wrong asset;
• unit conversion is missing;
• source equipment alias conflicts with another asset;
• AI-assisted suggestion was applied without enough review;
• source schema changed.

Actions:

1. Open the mapping.
2. Compare source preview with target value.
3. Confirm target entity and target ID.
4. Confirm transform expression.
5. Confirm unit and expected range.
6. Run sync again after correction.
7. Record the correction reason.

Sync is partial or failed

Check:

• read count;
• written count;
• failed count;
• recent connector errors;
• quota usage;
• mapping changes;
• rejected rows;
• source file or payload format changes.

If failed rows are available in the review queue, inspect source, dataset, connector, row index, raw payload, and reason before deciding whether to fix the source or adjust mapping.

Quality score drops

Common causes:

• missing fields;
• stale source data;
• invalid timestamp;
• impossible value range;
• unit mismatch;
• duplicated source records;
• source schema drift;
• connector polling delay.

Actions:

1. Compare quality trend with recent sync runs.
2. Review completeness, timeliness, and accuracy.
3. Check whether a source owner changed the source.
4. Confirm whether the drop affects downstream workflows.
5. Fix source, mapping, transform, or sync settings.

When to escalate

Escalate to engineering or the project integration owner when:

• connector test fails after source owner confirms settings;
• network route is blocked;
• connector type requires custom handling;
• source schema changed in a way mapping cannot handle;
• failed rows cannot be explained from the UI;
• production workflows depend on the missing data.

Include:

• connector name and ID;
• source type;
• error message;
• latest sync status;
• read, written, and failed counts;
• sample source path;
• mapping rule involved;
• source owner notes.