First-party product documentation. Instructions are verified against the dFlow~IQ desktop implementation. Labels appear exactly as they do in the application where practical.
Connection tests fail
- Confirm endpoint, DNS, VPN and firewall reachability.
- Match No Auth, SASL/PLAIN or SASL/SCRAM to the broker listener.
- For TLS, verify the trust file is readable and the certificate hostname matches every advertised broker.
- Expand Show stack trace in Connection test failed for local diagnosis.
- Treat Registry URL, trust and Basic credentials separately from Kafka.
Records do not decode or disappear
- Confirm key and value deserializers independently.
- Use the serialization guide to distinguish JSON, Registry framing, embedded Avro and raw bytes.
- Verify the selected Registry environment contains the record's schema ID.
- Record is no longer available in Kafka means retention removed the payload after metadata was indexed.
- Offset out of range means the requested position is outside the retained broker range.
Publishing fails
- Files over 32 KiB or 500 lines must use Batch Upload.
- Check numeric ranges, Base64/hex syntax, UUID format and JSON validity.
- For Avro, inspect required fields, union shape and enum symbols.
- Confirm topic Write authorization and end-to-end message-size limits.
- Use the acknowledged partition and offset to distinguish producer failure from downstream processing failure.
Pipeline or test cannot run
- Save all definition changes before dry run or preview.
- Any edit invalidates the current plan.
- A cancelled or failed run requires a fresh dry run or preview.
- Check source/output topic existence and permissions.
- Avoid partition-count changes while a bounded test is running.
Startup or workspace restoration fails
Malformed project or session JSON may require manual recovery because no complete repair interface is implemented.
- Quit dFlow~IQ.
- Back up ~/.dflowiq and the affected workspace file.
- Inspect session.json or the project JSON for truncation or invalid syntax.
- Move the malformed file aside rather than deleting it immediately.
- Restart and reopen a known-good workspace.
Never paste workspace files into public support channels without removing connection endpoints and passwords.
Capture useful evidence
- Application version and operating system.
- Workspace name without credentials.
- Exact UI action and error category.
- Topic, partition and offset where relevant.
- Sanitised stack trace from the connection dialog.
- Activity Log timestamp and action.
- Whether the issue reproduces in a controlled test environment.